@cosmicdrift/kumiko-bundled-features 0.97.0 → 0.98.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "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>",
@@ -91,11 +91,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.97.0",
-    "@cosmicdrift/kumiko-framework": "0.97.0",
-    "@cosmicdrift/kumiko-headless": "0.97.0",
-    "@cosmicdrift/kumiko-renderer": "0.97.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.97.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.98.0",
+    "@cosmicdrift/kumiko-framework": "0.98.0",
+    "@cosmicdrift/kumiko-headless": "0.98.0",
+    "@cosmicdrift/kumiko-renderer": "0.98.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.98.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

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

@@ -4,8 +4,9 @@ import { createTagsFeature } from "../feature";
 import {
   assignTagPayloadSchema,
   createTagPayloadSchema,
+  deleteTagPayloadSchema,
   removeTagPayloadSchema,
-  renameTagPayloadSchema,
+  updateTagPayloadSchema,
 } from "../schemas";
 
 // Unit tests: feature-shape, role-options, schema-validation. The ES-loop
@@ -47,7 +48,7 @@ function rawQueryAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch
 }
 
 describe("createTagsFeature shape", () => {
-  test("registers tag + tag-assignment entities, 4 write-handlers, 2 query-handlers", () => {
+  test("registers tag + tag-assignment entities, 5 write-handlers, 2 query-handlers", () => {
     const feature = createTagsFeature();
 
     expect(Object.keys(feature.entities ?? {})).toEqual(
@@ -57,12 +58,13 @@ describe("createTagsFeature shape", () => {
     expect(Object.keys(feature.writeHandlers)).toEqual(
       expect.arrayContaining([
         expect.stringMatching(/create-tag/),
-        expect.stringMatching(/rename-tag/),
+        expect.stringMatching(/update-tag/),
+        expect.stringMatching(/delete-tag/),
         expect.stringMatching(/assign-tag/),
         expect.stringMatching(/remove-tag/),
       ]),
     );
-    expect(Object.keys(feature.writeHandlers)).toHaveLength(4);
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(5);
 
     expect(Object.keys(feature.queryHandlers)).toEqual(
       expect.arrayContaining([
@@ -79,7 +81,8 @@ describe("createTagsFeature access-options", () => {
     const feature = createTagsFeature();
     expect(feature).toBe(createTagsFeature());
     expect(writeAccess(feature, "create-tag")).toEqual([...DEFAULT_TAG_ROLES]);
-    expect(writeAccess(feature, "rename-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(writeAccess(feature, "update-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+    expect(writeAccess(feature, "delete-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]);
@@ -89,7 +92,8 @@ describe("createTagsFeature access-options", () => {
   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, "rename-tag")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "update-tag")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "delete-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"]);
@@ -98,7 +102,7 @@ describe("createTagsFeature access-options", () => {
 
   test("access:{openToAll} applies to every write- and query-path", () => {
     const feature = createTagsFeature({ access: { openToAll: true } });
-    for (const path of ["create-tag", "rename-tag", "assign-tag", "remove-tag"]) {
+    for (const path of ["create-tag", "update-tag", "delete-tag", "assign-tag", "remove-tag"]) {
       expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
     }
     for (const query of ["tag:list", "tag-assignment:list"]) {
@@ -163,28 +167,57 @@ describe("createTagPayloadSchema", () => {
   });
 });
 
-describe("renameTagPayloadSchema", () => {
+describe("updateTagPayloadSchema", () => {
   const valid = { id: "tag-1", version: 0, name: "Neu" };
 
-  test("accepts id + version + name", () => {
-    expect(renameTagPayloadSchema.safeParse(valid).success).toBe(true);
+  test("accepts id + version + name (rename)", () => {
+    expect(updateTagPayloadSchema.safeParse(valid).success).toBe(true);
+  });
+
+  test("accepts color-only (recolor) and scope-only (re-scope)", () => {
+    expect(updateTagPayloadSchema.safeParse({ id: "t", version: 0, color: "#abc" }).success).toBe(
+      true,
+    );
+    expect(updateTagPayloadSchema.safeParse({ id: "t", version: 0, scope: "note" }).success).toBe(
+      true,
+    );
+  });
+
+  test("accepts color/scope = '' to clear them", () => {
+    expect(
+      updateTagPayloadSchema.safeParse({ id: "t", version: 0, color: "", scope: "" }).success,
+    ).toBe(true);
+  });
+
+  test("rejects a no-op (id + version, no mutable field)", () => {
+    expect(updateTagPayloadSchema.safeParse({ id: "tag-1", version: 0 }).success).toBe(false);
   });
 
   test("rejects a missing version (optimistic lock is mandatory)", () => {
-    expect(renameTagPayloadSchema.safeParse({ id: "tag-1", name: "Neu" }).success).toBe(false);
+    expect(updateTagPayloadSchema.safeParse({ id: "tag-1", name: "Neu" }).success).toBe(false);
   });
 
   test("rejects an empty name", () => {
-    expect(renameTagPayloadSchema.safeParse({ ...valid, name: "" }).success).toBe(false);
+    expect(updateTagPayloadSchema.safeParse({ ...valid, name: "" }).success).toBe(false);
   });
 
   test("rejects a name over 64 chars", () => {
-    expect(renameTagPayloadSchema.safeParse({ ...valid, name: "x".repeat(65) }).success).toBe(
+    expect(updateTagPayloadSchema.safeParse({ ...valid, name: "x".repeat(65) }).success).toBe(
       false,
     );
   });
 });
 
+describe("deleteTagPayloadSchema", () => {
+  test("accepts a bare id (no version — destructive intent)", () => {
+    expect(deleteTagPayloadSchema.safeParse({ id: "tag-1" }).success).toBe(true);
+  });
+
+  test("rejects an empty id", () => {
+    expect(deleteTagPayloadSchema.safeParse({ id: "" }).success).toBe(false);
+  });
+});
+
 describe("assign/remove payload schemas", () => {
   const valid = { tagId: "tag-1", entityType: "credit", entityId: "c-1" };
 

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

@@ -61,6 +61,10 @@ async function remove(tagId: string, entityType: string, entityId: string, user
   return stack.http.writeOk(TagsHandlers.removeTag, { tagId, entityType, entityId }, user);
 }
 
+async function deleteTag(id: string, user = admin) {
+  return stack.http.writeOk(TagsHandlers.deleteTag, { id }, user);
+}
+
 async function tagById(id: string, user = admin): Promise<Record<string, unknown> | undefined> {
   return (await listTags(user)).find((t) => t["id"] === id);
 }
@@ -147,7 +151,7 @@ describe("tags integration — rename", () => {
     expect(typeof before?.["version"]).toBe("number");
     const version = before?.["version"] as number;
 
-    await stack.http.writeOk(TagsHandlers.renameTag, { id, version, name: "Mandant Neu" }, admin);
+    await stack.http.writeOk(TagsHandlers.updateTag, { id, version, name: "Mandant Neu" }, admin);
 
     const after = await tagById(id);
     expect(after?.["name"]).toBe("Mandant Neu");
@@ -162,10 +166,10 @@ describe("tags integration — rename", () => {
       admin,
     );
     const stale = (await tagById(id))?.["version"] as number;
-    await stack.http.writeOk(TagsHandlers.renameTag, { id, version: stale, name: "Erster" }, admin);
+    await stack.http.writeOk(TagsHandlers.updateTag, { id, version: stale, name: "Erster" }, admin);
 
     const err = await stack.http.writeErr(
-      TagsHandlers.renameTag,
+      TagsHandlers.updateTag,
       { id, version: stale, name: "Zweiter" }, // stale: the row already moved to stale+1
       admin,
     );
@@ -182,7 +186,7 @@ describe("tags integration — rename", () => {
     const version = (await tagById(id, admin))?.["version"] as number;
 
     const err = await stack.http.writeErr(
-      TagsHandlers.renameTag,
+      TagsHandlers.updateTag,
       { id, version, name: "B-Übernahme" },
       otherTenant,
     );
@@ -191,6 +195,64 @@ describe("tags integration — rename", () => {
   });
 });
 
+describe("tags integration — update (recolor / re-scope)", () => {
+  test("update-tag changes color + scope, preserves the untouched name", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      TagsHandlers.createTag,
+      { name: "Projekt", color: "#111111" },
+      admin,
+    );
+    const version = (await tagById(id))?.["version"] as number;
+    await stack.http.writeOk(
+      TagsHandlers.updateTag,
+      { id, version, color: "#22cc88", scope: "note" },
+      admin,
+    );
+    const after = await tagById(id);
+    expect(after?.["name"]).toBe("Projekt");
+    expect(after?.["color"]).toBe("#22cc88");
+    expect(after?.["scope"]).toBe("note");
+  });
+
+  test("update-tag with empty color clears it", async () => {
+    const { id } = await stack.http.writeOk<{ id: string }>(
+      TagsHandlers.createTag,
+      { name: "Farbe", color: "#abcdef" },
+      admin,
+    );
+    const version = (await tagById(id))?.["version"] as number;
+    await stack.http.writeOk(TagsHandlers.updateTag, { id, version, color: "" }, admin);
+    expect((await tagById(id))?.["color"]).toBe("");
+  });
+});
+
+describe("tags integration — delete-tag cascade", () => {
+  test("deletes the tag and detaches it from every entity (multiple types)", async () => {
+    const target = await createTag("Sammelmappe");
+    const other = await createTag("bleibt");
+    // target spans two entityTypes; other tag stays attached to prove scoping
+    await assign(target, "credit", "credit-d1");
+    await assign(target, "note", "note-d1");
+    await assign(other, "credit", "credit-d1");
+    expect(await countAssignments(admin.tenantId)).toBe(3);
+
+    await deleteTag(target);
+
+    expect(await tagById(target)).toBeUndefined();
+    expect(await tagById(other)).toBeDefined();
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    expect(await listAssignments({ field: "tagId", op: "eq", value: target })).toHaveLength(0);
+    expect(await listAssignments({ field: "tagId", op: "eq", value: other })).toHaveLength(1);
+  });
+
+  test("deleting an already-gone tag is idempotent success", async () => {
+    const id = await createTag("einmalig");
+    await deleteTag(id);
+    await deleteTag(id); // second call must not error
+    expect(await tagById(id)).toBeUndefined();
+  });
+});
+
 describe("tags integration — many-to-many composition", () => {
   test("one entity carries multiple tags", async () => {
     const a = await createTag("rot");

package/src/tags/constants.ts

@@ -14,11 +14,21 @@ export const TAGS_FEATURE_NAME = "tags";
 // standalone use from `@cosmicdrift/kumiko-bundled-features/tags/web`.
 export const TAGS_SECTION_EXTENSION_NAME = "TagSection";
 
+// Registry name for the <TagFilter> header-slot control. A host entityList wires
+// it via `slots: { header: { react: { __component: TAGS_FILTER_EXTENSION_NAME } } }`
+// after mounting tagsClient(); the renderer passes it the list's screenId.
+export const TAGS_FILTER_EXTENSION_NAME = "TagFilter";
+
+// Screen-id of the standalone Tags management screen (custom screen rendering
+// TagManager). Qualified = "tags:screen:tag-list"; the app places it via r.nav.
+export const TAGS_SCREEN_ID = "tag-list";
+
 // 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",
-  renameTag: "tags:write:rename-tag",
+  updateTag: "tags:write:update-tag",
+  deleteTag: "tags:write:delete-tag",
   assignTag: "tags:write:assign-tag",
   removeTag: "tags:write:remove-tag",
 } as const;

package/src/tags/entity.ts

@@ -9,6 +9,10 @@ export const tagEntity = createEntity({
     name: createTextField({ required: true, maxLength: 64 }),
     // Optional UI hint (hex or token). No enforcement — purely for rendering.
     color: createTextField({ maxLength: 32 }),
+    // Optional entity-type scope (GitLab project-vs-group labels): empty = global
+    // (offered on every entity); a value like "note" restricts the tag to that
+    // entityType in the picker. No enforcement on assign — purely a picker hint.
+    scope: createTextField({ maxLength: 64 }),
   },
 });
 

package/src/tags/feature.ts

@@ -12,9 +12,9 @@
 // tag-assignments filtered on entityId (tags of an entity) or tagId (entities
 // with a tag). See entity.ts.
 //
-// Scope: create-tag, rename-tag, assign-tag, remove-tag, list tags, list assignments.
-// Deferred: delete-tag, optional host-projection decoration
-// (`wireTagsFor`), search indexing, user-data-rights anonymization.
+// Handlers: create-tag, update-tag (rename/recolor/re-scope), delete-tag
+// (cascades over assignments), assign-tag, remove-tag, list tags, list assignments.
+// Deferred: optional host-projection decoration (`wireTagsFor`), search indexing.
 
 import {
   type AccessRule,
@@ -22,12 +22,13 @@ import {
   defineFeature,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants";
+import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME, TAGS_SCREEN_ID } from "./constants";
 import { tagAssignmentEntity, tagEntity } from "./entity";
 import { createAssignTagHandler } from "./handlers/assign-tag.write";
 import { createCreateTagHandler } from "./handlers/create-tag.write";
+import { createDeleteTagHandler } from "./handlers/delete-tag.write";
 import { createRemoveTagHandler } from "./handlers/remove-tag.write";
-import { createRenameTagHandler } from "./handlers/rename-tag.write";
+import { createUpdateTagHandler } from "./handlers/update-tag.write";
 
 // Opt-in tier-gating: when set, the feature declares itself r.toggleable so the
 // dispatcher gate + feature-toggles + tier-engine can switch the WHOLE feature
@@ -43,7 +44,7 @@ function registerTags(
   toggleable: TagsToggleable | undefined,
 ): 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`, `rename-tag` (optimistic-locked), `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 }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
+    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `update-tag` (optimistic-locked rename/recolor/re-scope), `delete-tag` (cascades over assignments), `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );
   r.uiHints({
     displayLabel: "Tags",
@@ -59,12 +60,22 @@ function registerTags(
   r.entity("tag-assignment", tagAssignmentEntity);
 
   r.writeHandler(createCreateTagHandler(access));
-  r.writeHandler(createRenameTagHandler(access));
+  r.writeHandler(createUpdateTagHandler(access));
+  r.writeHandler(createDeleteTagHandler(access));
   r.writeHandler(createAssignTagHandler(access));
   r.writeHandler(createRemoveTagHandler(access));
 
   r.queryHandler(defineEntityListHandler("tag", tagEntity, { access }));
   r.queryHandler(defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access }));
+
+  // Standalone Tags management screen (custom React: TagManager). The app places
+  // it in nav via r.nav("tags:screen:tag-list"); tagsClient() maps the component.
+  r.screen({
+    id: TAGS_SCREEN_ID,
+    type: "custom",
+    renderer: { react: { __component: "TagsScreen" } },
+    access,
+  });
 }
 
 export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>

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

@@ -6,7 +6,7 @@ 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 is rename-tag.write.ts; delete is still deferred.
+// tags). Editing is update-tag.write.ts; delete (with cascade) is delete-tag.write.ts.
 export function createCreateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
   return {
     name: "create-tag",

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

@@ -0,0 +1,54 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagAssignmentExecutor, tagExecutor } from "../executor";
+import { type DeleteTagPayload, deleteTagPayloadSchema } from "../schemas";
+
+const CASCADE_PAGE = 200;
+
+// delete-tag — removes a tag from the catalog and detaches it everywhere. No FK
+// (event-sourced, no JOIN), so the handler cascades: soft-delete every
+// assignment carrying this tag, then hard-delete the catalog tag.
+//
+// Idempotent: deleting an already-gone tag returns success (mirrors remove-tag).
+//
+// The cascade re-reads page 1 (no cursor) until it comes back empty instead of
+// paging with a cursor: assignment deletes are soft-deletes and the list query
+// hides isDeleted rows, so a keyset cursor over the shrinking result set would
+// silently skip rows. Re-reading the head always returns the remaining live
+// rows and terminates when none are left.
+export function createDeleteTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "delete-tag",
+    schema: deleteTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as DeleteTagPayload; // @cast-boundary engine-payload
+
+      const existing = await tagExecutor.detail({ id: payload.id }, event.user, ctx.db);
+      if (!existing) {
+        return { isSuccess: true as const, data: { id: payload.id } };
+      }
+
+      for (;;) {
+        const page = await tagAssignmentExecutor.list(
+          { filter: { field: "tagId", op: "eq", value: payload.id }, limit: CASCADE_PAGE },
+          event.user,
+          ctx.db,
+        );
+        if (page.rows.length === 0) break;
+        for (const row of page.rows) {
+          const removed = await tagAssignmentExecutor.delete(
+            { id: String(row["id"]) },
+            event.user,
+            ctx.db,
+          );
+          if (!removed.isSuccess) return removed;
+        }
+      }
+
+      return tagExecutor.delete({ id: payload.id }, event.user, ctx.db);
+    },
+  };
+}
+
+export const deleteTagHandler: WriteHandlerDef = createDeleteTagHandler();

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

@@ -0,0 +1,31 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagExecutor } from "../executor";
+import { type UpdateTagPayload, updateTagPayloadSchema } from "../schemas";
+
+// update-tag — edits a catalog tag (rename / recolor / re-scope). Optimistic-
+// locked: the client sends the `version` it read (mirrors tenant:update). Only
+// the fields present in the payload go into `changes`, and the executor merges
+// shallowly, so any omitted field is preserved (color/scope accept "" to clear).
+// A stale version returns version_conflict; the UI refetches and retries.
+export function createUpdateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "update-tag",
+    schema: updateTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as UpdateTagPayload; // @cast-boundary engine-payload
+      const changes: Record<string, unknown> = {};
+      if (payload.name !== undefined) changes["name"] = payload.name;
+      if (payload.color !== undefined) changes["color"] = payload.color;
+      if (payload.scope !== undefined) changes["scope"] = payload.scope;
+      return tagExecutor.update(
+        { id: payload.id, version: payload.version, changes },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const updateTagHandler: WriteHandlerDef = createUpdateTagHandler();

package/src/tags/index.ts

@@ -3,6 +3,9 @@ export {
   DEFAULT_TAG_ACCESS,
   DEFAULT_TAG_ROLES,
   TAGS_FEATURE_NAME,
+  TAGS_FILTER_EXTENSION_NAME,
+  TAGS_SCREEN_ID,
+  TAGS_SECTION_EXTENSION_NAME,
   TagsHandlers,
   TagsQueries,
 } from "./constants";
@@ -16,21 +19,27 @@ export {
   createCreateTagHandler,
   createTagHandler,
 } from "./handlers/create-tag.write";
+export {
+  createDeleteTagHandler,
+  deleteTagHandler,
+} from "./handlers/delete-tag.write";
 export {
   createRemoveTagHandler,
   removeTagHandler,
 } from "./handlers/remove-tag.write";
 export {
-  createRenameTagHandler,
-  renameTagHandler,
-} from "./handlers/rename-tag.write";
+  createUpdateTagHandler,
+  updateTagHandler,
+} from "./handlers/update-tag.write";
 export {
   type AssignTagPayload,
   assignTagPayloadSchema,
   type CreateTagPayload,
   createTagPayloadSchema,
+  type DeleteTagPayload,
+  deleteTagPayloadSchema,
   type RemoveTagPayload,
-  type RenameTagPayload,
   removeTagPayloadSchema,
-  renameTagPayloadSchema,
+  type UpdateTagPayload,
+  updateTagPayloadSchema,
 } from "./schemas";

package/src/tags/schemas.ts

@@ -3,17 +3,36 @@ import { z } from "zod";
 export const createTagPayloadSchema = z.object({
   name: z.string().min(1).max(64),
   color: z.string().max(32).optional(),
+  scope: z.string().max(64).optional(),
 });
 export type CreateTagPayload = z.infer<typeof createTagPayloadSchema>;
 
-// rename-tag — id + the version the client read (optimistic lock, mirrors
-// tenant:update) + the new name. The executor merges shallowly, so color stays.
-export const renameTagPayloadSchema = z.object({
+// update-tag — id + the version the client read (optimistic lock, mirrors
+// tenant:update) + the fields to change. name/color/scope are each optional so
+// the management UI can rename, recolor or re-scope independently; the executor
+// shallow-merges, so any field left undefined is preserved. color/scope accept ""
+// to clear them. At least one mutable field must be present (no-op guard).
+export const updateTagPayloadSchema = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().nonnegative(),
+    name: z.string().min(1).max(64).optional(),
+    color: z.string().max(32).optional(),
+    scope: z.string().max(64).optional(),
+  })
+  .refine((p) => p.name !== undefined || p.color !== undefined || p.scope !== undefined, {
+    message: "update-tag needs at least one of name, color or scope",
+  });
+export type UpdateTagPayload = z.infer<typeof updateTagPayloadSchema>;
+
+// delete-tag — hard-deletes the catalog tag AND cascades a soft-delete over
+// every assignment carrying it (no FK, so the handler does the cascade). No
+// version: deleting a label is a destructive "make it gone" intent — last writer
+// wins toward deletion rather than 409-ing on a concurrent rename. Idempotent.
+export const deleteTagPayloadSchema = z.object({
   id: z.string().min(1),
-  version: z.number().int().nonnegative(),
-  name: z.string().min(1).max(64),
 });
-export type RenameTagPayload = z.infer<typeof renameTagPayloadSchema>;
+export type DeleteTagPayload = z.infer<typeof deleteTagPayloadSchema>;
 
 // assign + remove share the (tag, entity) reference shape.
 const entityTagRef = {

package/src/tags/web/__tests__/entity-tags.test.tsx

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../../constants";
+import { EntityTags } from "../entity-tags";
+import { defaultTranslations } from "../i18n";
+
+type TagRow = { id: string; name: string; color?: string };
+type AssignmentRow = { tagId: string; entityType: string; entityId: string };
+
+let catalogRows: readonly TagRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+
+beforeEach(() => {
+  catalogRows = [];
+  assignmentRows = [];
+});
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === TagsQueries.tagList ? { rows: catalogRows } : { rows: assignmentRows },
+  loading: false,
+  error: null,
+  refetch: mock(async () => {}),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useQuery: useQuerySpy,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("EntityTags", () => {
+  test("renders a chip per assigned tag, joined to the catalog by id", () => {
+    catalogRows = [
+      { id: "t1", name: "important", color: "#ef4444" },
+      { id: "t2", name: "project-x", color: "#3b82f6" },
+    ];
+    assignmentRows = [
+      { tagId: "t1", entityType: "note", entityId: "n1" },
+      { tagId: "t2", entityType: "note", entityId: "n1" },
+    ];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("entity-tags")).toBeTruthy();
+    expect(screen.getByText("important")).toBeTruthy();
+    expect(screen.getByText("project-x")).toBeTruthy();
+  });
+
+  test("renders nothing when the entity has no assignments", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+    expect(screen.queryByTestId("tag-chip")).toBeNull();
+  });
+
+  test("ignores assignments belonging to a different entityType", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "invoice", entityId: "n1" }];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+  });
+
+  test("renders nothing for a not-yet-saved entity (entityId null)", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "n1" }];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId={null} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+  });
+});