@cosmicdrift/kumiko-bundled-features 0.57.2 → 0.60.0

package/src/subscription-stripe/__tests__/runtime.test.ts

@@ -5,22 +5,40 @@
 // (das deckt der Integration-Test ab).
 
 import { describe, expect, test } from "bun:test";
-import type { ConfigKeyHandle, HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type ConfigKeyHandle,
+  type HandlerContext,
+  qn,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import { createSecret, type SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import Stripe from "stripe";
+import {
+  STRIPE_API_KEY_CONFIG,
+  STRIPE_BILLING_LIVE_CONFIG,
+  STRIPE_WEBHOOK_SECRET_CONFIG,
+  SUBSCRIPTION_STRIPE_FEATURE,
+} from "../constants";
 import { createStripeClientCache, createStripeRuntimes } from "../runtime";
 
+// Handle-Namen aus den kanonischen Konstanten + demselben Qualifier ableiten,
+// den r.config zur Build-Zeit anwendet (define-feature.ts: qn(toKebab(feature),
+// "config", toKebab(shortKey))). Eine hand-redeklarierte Fixture konnte still
+// von der Produktion driften (#421/2) — diese Ableitung macht das unmöglich.
+const configHandleName = (shortKey: string): string =>
+  qn(toKebab(SUBSCRIPTION_STRIPE_FEATURE), "config", toKebab(shortKey));
+
 const API_KEY_HANDLE: ConfigKeyHandle<"text"> = {
-  name: "subscription-stripe:config:api-key",
+  name: configHandleName(STRIPE_API_KEY_CONFIG),
   type: "text",
 };
 const WEBHOOK_SECRET_HANDLE: ConfigKeyHandle<"text"> = {
-  name: "subscription-stripe:config:webhook-secret",
+  name: configHandleName(STRIPE_WEBHOOK_SECRET_CONFIG),
   type: "text",
 };
 const BILLING_LIVE_HANDLE: ConfigKeyHandle<"boolean"> = {
-  name: "subscription-stripe:config:billing-live",
+  name: configHandleName(STRIPE_BILLING_LIVE_CONFIG),
   type: "boolean",
 };
 
@@ -42,13 +60,36 @@ function stubSecrets(values: Record<string, string>): SecretsContext {
   };
 }
 
+/** Wie stubSecrets, aber speichert den Wert ROH (kein JSON.stringify) — um
+ *  parseStoredSecret's Fehlerpfad zu treffen: ein Credential, das der Store
+ *  un-JSON-kodiert zurückgibt (Korruption oder ein außerhalb des
+ *  backing:"secrets"-Roundtrips geschriebener Wert) muss laut failen, nicht
+ *  still Müll liefern. */
+function rawSecretsStub(values: Record<string, string>): SecretsContext {
+  const nameOf = (k: string | { readonly name: string }): string =>
+    typeof k === "string" ? k : k.name;
+  return {
+    get: async (_tenantId, key) => {
+      const value = values[nameOf(key)];
+      return value === undefined ? undefined : createSecret(value); // RAW, not JSON
+    },
+    has: async (_tenantId, key) => values[nameOf(key)] !== undefined,
+    set: async () => undefined,
+    delete: async () => false,
+  };
+}
+
 /** Minimaler HandlerContext-Stub mit nur den Feldern, die die ctx-
  *  Resolution liest (secrets, _userId für audit, config). */
 function stubCtx(opts: { secrets?: SecretsContext; billingLive?: boolean }): HandlerContext {
   return {
     secrets: opts.secrets,
     _userId: "tester",
-    config: async () => opts.billingLive,
+    // Key-aware: antwortet NUR auf das billing-live-Handle. Liest
+    // assertBillingLive versehentlich einen anderen Config-Key, kommt undefined
+    // zurück → Gate schließt → der "passes when true"-Test schlägt fehl (#421/3).
+    config: async (handle: ConfigKeyHandle<"boolean">) =>
+      handle.name === BILLING_LIVE_HANDLE.name ? opts.billingLive : undefined,
   } as unknown as HandlerContext; // @cast-boundary test-stub — partial ctx
 }
 
@@ -116,6 +157,19 @@ describe("StripeCtxRuntime.clientForCtx", () => {
     const ctx = stubCtx({ secrets: stubSecrets({}) });
     await expect(rt.ctx.clientForCtx(ctx)).rejects.toBeInstanceOf(UnconfiguredError);
   });
+
+  test("throws loudly on a malformed (non-JSON) stored credential (#393/2)", async () => {
+    // The store round-trips backing:"secrets" values JSON-encoded; a raw,
+    // un-quoted value reaching parseStoredSecret means corruption — it must
+    // throw, not silently fall through to undefined/fallback.
+    const rt = makeRuntimes({ apiKey: "sk_test_fallback" });
+    const ctx = stubCtx({
+      secrets: rawSecretsStub({ [API_KEY_HANDLE.name]: "sk_test_raw_unquoted" }),
+    });
+    await expect(rt.ctx.clientForCtx(ctx)).rejects.toThrow(
+      /Invalid JSON in subscription-stripe credential/,
+    );
+  });
 });
 
 // =============================================================================

package/src/subscription-stripe/__tests__/stripe-foundation.integration.test.ts

@@ -447,3 +447,108 @@ describe("scenario 5: runtime-secret resolution", () => {
     expect(res.status).toBe(401);
   });
 });
+
+// =============================================================================
+// Scenario 6: billing-live-Gate (#104) durch den vollen Stack.
+//
+// Die #104-Invariante (kein Live-Checkout solange billing-live nicht true) war
+// bislang nur mit gestubbter ctx.config getestet (runtime.test.ts) — kein Test
+// fuhr die Kette factory → r.config → ctx.config(handle) real durch. Eigener
+// Stack OHNE api-key/webhook-secret-Fallback, damit das Gate-Öffnen hermetisch
+// als UnconfiguredError sichtbar wird (api-key fehlt) statt in einem echten
+// Stripe-Netzwerk-Call. Ein reiner default-off-Beweis genügt nicht: er kann
+// "korrektes Handle, Wert fehlt" nicht von "falsches Handle, immer undefined"
+// trennen (beide → feature_disabled). Erst der positive Fall (billing-live via
+// config:write:set auf dem kanonischen QN setzen → Gate öffnet) beweist die
+// Handle-Resolution real.
+// =============================================================================
+
+const BILLING_LIVE_CONFIG_QN = "subscription-stripe:config:billing-live";
+
+describe("scenario 6: billing-live gate end-to-end (#104)", () => {
+  let gateStack: TestStack;
+
+  beforeAll(async () => {
+    const stripeFeature = createSubscriptionStripeFeature({ priceToTier: PRICE_TO_TIER });
+    const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
+    const resolver = createConfigResolver({ encryption });
+    const masterKeyProvider = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      },
+    });
+    gateStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createSecretsFeature(),
+        billingFoundationFeature,
+        stripeFeature,
+      ],
+      masterKeyProvider,
+      extraContext: ({ db: ctxDb, registry }) => ({
+        configResolver: resolver,
+        configEncryption: encryption,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+        secrets: createSecretsContext({ db: ctxDb, masterKeyProvider }),
+      }),
+    });
+    await createEventsTable(gateStack.db);
+    await unsafePushTables(gateStack.db, {
+      configValuesTable,
+      tenant_secrets: tenantSecretsTable,
+    });
+  });
+
+  afterAll(async () => {
+    await gateStack.cleanup();
+  });
+
+  const checkoutPayload = {
+    providerName: "stripe",
+    priceId: "price_pro_monthly",
+    successUrl: "https://app.example.com/ok",
+    cancelUrl: "https://app.example.com/cancel",
+  };
+
+  test("default-off → feature_disabled; config-flip → Gate öffnet (Handle-Resolution real)", async () => {
+    const tenantAdmin = createTestUser({
+      id: 6001,
+      tenantId: testTenantId(6001),
+      roles: ["TenantAdmin"],
+    });
+
+    // billing-live ungesetzt → Gate zu, throw VOR jedem api-key/Stripe-Schritt.
+    const closed = await gateStack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      checkoutPayload,
+      tenantAdmin,
+    );
+    expect(closed.code).toBe("feature_disabled");
+
+    // billing-live=true auf dem kanonischen QN setzen (was der abgeleitete
+    // Sysadmin-configEdit-Screen in prod dispatcht).
+    const sysAdmin = createTestUser({
+      id: 6002,
+      tenantId: SYSTEM_TENANT_ID,
+      roles: ["SystemAdmin"],
+    });
+    await gateStack.http.writeOk(
+      "config:write:set",
+      { key: BILLING_LIVE_CONFIG_QN, value: true, scope: "system" },
+      sysAdmin,
+    );
+
+    // Gate jetzt offen: nicht mehr feature_disabled. Der nächste Schritt
+    // (api-key-Resolution) schlägt fehl, weil weder secret noch fallback
+    // gesetzt sind → unconfigured. Wäre der billing-live-Handle falsch
+    // qualifiziert, bliebe ctx.config undefined → Fehler weiter feature_disabled.
+    const opened = await gateStack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      checkoutPayload,
+      tenantAdmin,
+    );
+    expect(opened.code).not.toBe("feature_disabled");
+    expect(opened.code).toBe("unconfigured");
+  });
+});

package/src/subscription-stripe/feature.ts

@@ -13,7 +13,8 @@
 //     wird er als config-Key. `mask` leitet den Sysadmin-configEdit-Screen
 //     + Settings-Hub-Nav ab — kein handgeschriebenes r.screen/r.nav in der
 //     App mehr (v2 hatte die Keys als `r.secret` + App-eigene Maske).
-//   - `subscription-stripe:config:billingLive` → **system config**
+//   - `subscription-stripe:config:billing-live` (shortKey `billingLive`,
+//     kebab-qualifiziert von r.config) → **system config**
 //     (boolean, default false). Der Master-Switch: ohne ihn darf kein
 //     checkout eine Stripe-Session erzeugen (#104-Invariante, write-side
 //     im createCheckoutSession-Gate durchgesetzt).

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,155 @@
+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;
+}
+
+function rawWriteAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch: string): unknown {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  return entry[1].access;
+}
+
+function rawQueryAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch: string): unknown {
+  const entry = Object.entries(feature.queryHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`query ${nameMatch} not registered`);
+  return entry[1].access;
+}
+
+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"]);
+  });
+
+  test("access:{openToAll} applies to every write- and query-path", () => {
+    const feature = createTagsFeature({ access: { openToAll: true } });
+    for (const path of ["create-tag", "assign-tag", "remove-tag"]) {
+      expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
+    }
+    for (const query of ["tag:list", "tag-assignment:list"]) {
+      expect(rawQueryAccess(feature, query)).toEqual({ openToAll: true });
+    }
+  });
+
+  test("access takes precedence over the roles shorthand", () => {
+    const feature = createTagsFeature({ access: { openToAll: true }, roles: ["Admin"] });
+    expect(rawWriteAccess(feature, "create-tag")).toEqual({ openToAll: true });
+    expect(rawQueryAccess(feature, "tag:list")).toEqual({ openToAll: true });
+  });
+
+  test("access:{roles} threads through like the roles shorthand", () => {
+    const feature = createTagsFeature({ access: { roles: ["Owner"] } });
+    expect(writeAccess(feature, "remove-tag")).toEqual(["Owner"]);
+    expect(queryAccess(feature, "tag-assignment:list")).toEqual(["Owner"]);
+  });
+});
+
+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,251 @@
+// 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);
+  });
+});
+
+// The access option must reach the runtime, not just the handler shape: a host
+// that mounts tags with openToAll lets a user WITHOUT any default tag role tag
+// freely (the exact failure that bit money-horse, whose signup users carry
+// "Admin", not "TenantAdmin"). Default-mounted tags deny that same user.
+describe("tags integration — openToAll access model", () => {
+  let openStack: TestStack;
+  // role deliberately not in DEFAULT_TAG_ROLES nor "Admin" — proves openToAll,
+  // not an accidental role match.
+  const unprivileged = createTestUser({ roles: ["Viewer"] });
+
+  beforeAll(async () => {
+    openStack = await setupTestStack({
+      features: [createTagsFeature({ access: { openToAll: true } })],
+    });
+    await unsafeCreateEntityTable(openStack.db, tagEntity);
+    await unsafeCreateEntityTable(openStack.db, tagAssignmentEntity);
+    await createEventsTable(openStack.db);
+  });
+
+  afterAll(async () => {
+    await openStack.cleanup();
+  });
+
+  test("a non-tag-role user can create, assign, list and remove", async () => {
+    const tag = await openStack.http.writeOk<{ id: string }>(
+      TagsHandlers.createTag,
+      { name: "Paket A" },
+      unprivileged,
+    );
+    await openStack.http.writeOk(
+      TagsHandlers.assignTag,
+      { tagId: tag.id, entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+
+    const tags = await openStack.http.queryOk<{ rows: unknown[] }>(
+      TagsQueries.tagList,
+      {},
+      unprivileged,
+    );
+    expect(tags.rows).toHaveLength(1);
+
+    const assigned = await openStack.http.queryOk<{ rows: unknown[] }>(
+      TagsQueries.assignmentList,
+      { filter: { field: "entityId", op: "eq", value: "c-1" } },
+      unprivileged,
+    );
+    expect(assigned.rows).toHaveLength(1);
+
+    await openStack.http.writeOk(
+      TagsHandlers.removeTag,
+      { tagId: tag.id, entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+  });
+
+  test("the SAME user is denied on a default-role-mounted feature", async () => {
+    const denied = await stack.http.writeErr(
+      TagsHandlers.createTag,
+      { name: "nope" },
+      unprivileged,
+    );
+    expect(denied.httpStatus).toBe(403);
+  });
+});