@cosmicdrift/kumiko-bundled-features 0.97.1 → 0.100.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.97.1",
+  "version": "0.100.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.1",
-    "@cosmicdrift/kumiko-framework": "0.97.1",
-    "@cosmicdrift/kumiko-headless": "0.97.1",
-    "@cosmicdrift/kumiko-renderer": "0.97.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.97.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.100.0",
+    "@cosmicdrift/kumiko-framework": "0.100.0",
+    "@cosmicdrift/kumiko-headless": "0.100.0",
+    "@cosmicdrift/kumiko-renderer": "0.100.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.100.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/file-foundation/feature.ts

@@ -1,103 +1,44 @@
 // kumiko-feature-version: 1
 //
-// file-foundation as a Kumiko bundled feature — plugin-API shape.
+// file-foundation as a Kumiko bundled feature — declares the `fileProvider`
+// extension point + the per-tenant `provider` config key. Provider RESOLUTION
+// (createFileProviderForTenant) + the plugin types now live in the framework
+// (packages/framework/src/files/provider-resolver.ts) so the upload routes,
+// `ctx.files` and the GDPR jobs resolve through ONE path — uploads, export and
+// erasure hit the same store by construction. This feature re-exports the moved
+// symbols unchanged so existing imports keep working.
 //
-// **Pattern-Vorbild:** identisch zu `mail-foundation`. Foundation
-// deklariert extension-point `fileProvider`, Provider-Features (file-
-// provider-s3, später file-provider-azure-blob, file-provider-gcs)
-// registrieren sich namentlich. Tenant wählt zur Runtime via config-
-// key `provider`.
+// **Pattern-Vorbild:** identisch zu `mail-foundation`. Foundation deklariert
+// extension-point `fileProvider`, Provider-Features (file-provider-s3, -inmemory,
+// -s3-env, später -gcs/-azure-blob) registrieren sich namentlich. Tenant wählt
+// zur Runtime via config-key `provider`.
 //
-// **Was diese Foundation NICHT mehr macht:**
-//   - Keine S3-spezifischen Config-Keys mehr (bucket/region/endpoint/
-//     forcePathStyle/accessKeyId) — die leben im Provider-Plugin.
-//   - Kein direkter Import von `createS3Provider`. Foundation kennt
-//     nur das `FileStorageProvider`-Interface (Type-Import, kein
-//     runtime-coupling).
-//
-// **Standalone:** Foundation ist ohne tier-engine nutzbar. Existing
-// `files-provider-s3` (App-wide-Library) bleibt unangetastet.
-//
-// **Boot-Dependencies:** config (für provider-selector). Kein secrets,
-// weil Foundation selbst keine Secrets hält.
+// **Boot-Dependencies:** config (für provider-selector). Kein secrets, weil
+// Foundation selbst keine Secrets hält.
 
-import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   access,
-  type ConfigAccessor,
   createTenantConfig,
   defineFeature,
-  type Registry,
+  EXT_FILE_PROVIDER,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
-
-const FEATURE_NAME = "file-foundation";
-
-// =============================================================================
-// Plugin-Interface — what a Provider-Plugin must implement
-// =============================================================================
-
-/**
- * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu
- * fett (haelt tx, actor, signal etc.) — Provider sollen sich auf die
- * read-Felder beschraenken die fuer Tenant-Config + Secret-Lookup
- * gebraucht werden.
- *
- * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt
- * es keinen request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider
- * `ctx.tx` lesen wuerde, wuerde der ganze Worker-Pfad zur Runtime
- * brechen — und das wuerde NUR mit S3 und nur in production auffallen.
- * Die schmale Surface zwingt Provider zur expliziten Erweiterung
- * (extra-arg) statt silent ctx-feld-ausnutzen.
- *
- * **Felder:**
- *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
- *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
- *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
- *   _userId — Audit-Identity fuer secret-reads. Im Handler-Pfad setzt
- *             der dispatcher das auf die Caller-User-ID; im Worker-Pfad
- *             muss der r.job-Wrap das explizit auf eine System-Identity
- *             setzen (z.B. "system:user-data-rights:run-export-jobs").
- */
-export type FileProviderContext = {
-  readonly config?: ConfigAccessor;
-  readonly registry?: Registry;
-  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
-  readonly _userId?: string | undefined;
-};
-
-/**
- * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
- * file-provider-azure-blob, ...) registers an implementation via
- * `r.useExtension("fileProvider", "<name>", { build })`.
- *
- * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext,
- * nicht ein voller HandlerContext. Felder ausserhalb der schmalen
- * Surface (z.B. `ctx.tx`, `ctx.actor`, `ctx.signal`, `ctx.notify`) sind
- * im Worker-Pfad (r.job-getriggerte Provider-Builds) NICHT vorhanden.
- * Cast `ctx as unknown as HandlerContext` macht den Compiler happy aber
- * fliegt zur Runtime im Worker — und der Crash kommt erst in production
- * mit dem ersten S3-Tenant. Wenn ein Plugin Felder braucht die nicht in
- * FileProviderContext sind: lieber FileProviderContext explizit erweitern
- * (sichtbarer breaking change) als ctx-cast.
- */
-export type FileProviderPlugin = {
-  readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
-};
 
-// extension-usage `options` is engine-payload (unknown) — structurally validate
-// instead of casting blind.
-export function isFileProviderPlugin(o: unknown): o is FileProviderPlugin {
-  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
-}
+export type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-framework/files";
+// Moved into the framework — re-exported here so `@cosmicdrift/kumiko-bundled-
+// features/file-foundation` consumers (user-data-rights, app code) keep working.
+export {
+  createFileProviderForTenant,
+  isFileProviderPlugin,
+} from "@cosmicdrift/kumiko-framework/files";
 
-// =============================================================================
-// Feature-definition
-// =============================================================================
+const FEATURE_NAME = "file-foundation";
 
 export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` \u2014 use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
+    "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` — use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
   );
   r.uiHints({
     displayLabel: "File Provider Foundation",
@@ -106,7 +47,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   });
   r.requires("config");
 
-  r.extendsRegistrar("fileProvider", {
+  r.extendsRegistrar(EXT_FILE_PROVIDER, {
     onRegister: () => {
       // No side-effects at register-time — registry stores the usage,
       // factory looks it up at request-time.
@@ -124,61 +65,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   });
   // Readiness gating: provider-plugins' required keys/secrets count only
   // while their plugin is the one this key selects.
-  r.extensionSelector("fileProvider", configKeys.provider);
+  r.extensionSelector(EXT_FILE_PROVIDER, configKeys.provider);
 
   return { configKeys };
 });
-
-// =============================================================================
-// Provider-factory — looks up the registered plugin + delegates
-// =============================================================================
-
-export async function createFileProviderForTenant(
-  ctx: FileProviderContext,
-  tenantId: string,
-  handlerName = "file-foundation:provider-factory",
-): Promise<FileStorageProvider> {
-  const ctxConfig = ctx.config;
-  if (!ctxConfig) {
-    throw new Error(
-      `${handlerName}: ctx.config is missing — feature requires the config-feature mounted in the registry`,
-    );
-  }
-  if (!ctx.registry) {
-    throw new Error(
-      `${handlerName}: ctx.registry is missing — required to look up registered file-provider plugins`,
-    );
-  }
-
-  const provider = requireDefined(
-    await ctxConfig(fileFoundationFeature.exports.configKeys.provider),
-    FEATURE_NAME,
-    "provider",
-  ) as string; // @cast-boundary engine-payload
-  if (provider.length === 0) {
-    const usages = ctx.registry.getExtensionUsages("fileProvider");
-    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
-    throw new Error(
-      `${FEATURE_NAME}: no provider selected — set the 'provider' config-key to one of: ${known}. ` +
-        `Mount a file-provider-* feature first if no plugins are registered.`,
-    );
-  }
-
-  const usages = ctx.registry.getExtensionUsages("fileProvider");
-  const usage = usages.find((u) => u.entityName === provider);
-  if (!usage) {
-    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
-    throw new Error(
-      `${FEATURE_NAME}: provider "${provider}" not registered. Known: ${known}. ` +
-        `Mount the matching file-provider-${provider} feature.`,
-    );
-  }
-
-  if (!isFileProviderPlugin(usage.options)) {
-    throw new Error(
-      `${FEATURE_NAME}: provider "${provider}" registered without a build() — ` +
-        `extension options must be a FileProviderPlugin.`,
-    );
-  }
-  return usage.options.build(ctx, tenantId);
-}

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,27 @@ 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";
+
+// Registry name for the <TagsCell> column renderer. A host entityList shows an
+// entity's tags inline by declaring a labeled virtual column:
+// `{ field: "tags", label: "Tags", renderer: { react: { __component: TAGS_COLUMN_RENDERER_NAME } } }`
+// after mounting tagsClient() (which registers it under clientFeatures.columnRenderers).
+export const TAGS_COLUMN_RENDERER_NAME = "TagsCell";
+
+// 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();