@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/tags/constants.ts

@@ -0,0 +1,61 @@
+// @runtime client
+// tags bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/features/tags.md
+// C#1 design: money-horse/docs/plans/cashcolt-vertragspakete.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const TAGS_FEATURE_NAME = "tags";
+
+// Registry name for the drop-in <TagSection> component. Apps reference it in a
+// screen schema via `component: { react: { __component: TAGS_SECTION_EXTENSION_NAME } }`
+// after mounting tagsClient(); the component is also importable directly for
+// 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-ids for the declarative tag catalog (entityList + entityEdit).
+// Qualified list = "tags:screen:tag-list"; the app places it via r.nav.
+export const TAGS_SCREEN_ID = "tag-list";
+export const TAGS_EDIT_SCREEN_ID = "tag-edit";
+
+// 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",
+  updateTag: "tags:write:update-tag",
+  deleteTag: "tags:write:delete-tag",
+  assignTag: "tags:write:assign-tag",
+  removeTag: "tags:write:remove-tag",
+} as const;
+
+export const TagsQueries = {
+  // defineEntityListHandler("tag", ...) → "tag:list", qualified by the feature
+  // to "tags:query:tag:list".
+  tagList: "tags:query:tag:list",
+  assignmentList: "tags:query:tag-assignment:list",
+} as const;
+
+// Default RBAC for every tag write/read path. Tags are a low-sensitivity
+// collaboration tool, so both tenant roles may use them. Apps with their own
+// role vocabulary (e.g. "Admin"/"Editor") override via createTagsFeature({ roles }),
+// or adopt the host's whole access model with createTagsFeature({ access }) —
+// otherwise the hard-wired QNs are access_denied for their users.
+export const DEFAULT_TAG_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+// The default access rule applied to every tag handler when the app passes
+// neither `access` nor `roles`. createTagsFeature({ access: { openToAll: { reason } } })
+// makes tagging reachable for any authenticated tenant user — matching apps
+// whose other handlers are openToAll rather than role-gated.
+export const DEFAULT_TAG_ACCESS: AccessRule = { roles: DEFAULT_TAG_ROLES };

package/packages/bundled-features/src/tags/entity.ts

@@ -0,0 +1,99 @@
+import {
+  createEntity,
+  createTextField,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// tag — per-tenant tag catalog. Event-sourced entity (create/rename/delete via
+// the standard executor); the framework projects `read_tags` from its own CRUD
+// events. tenantId is a base column set by the framework → tenant-scoped.
+export const tagEntity = createEntity({
+  table: "read_tags",
+  description:
+    "One entry of a tenant's tag catalog: a name plus an optional colour hint for rendering and an optional entityType scope that limits which entities a picker offers the tag on. Names are not unique, and a tag carries no link to the entities it is attached to.",
+  fields: {
+    // Catalog labels ("urgent", "billing"), not user-identifying content —
+    // `personal: false` silences the user-content heuristic (456/5). A tag
+    // has no author to anchor a `personal: { of: "<f>" }` annotation to, and
+    // a tag isn't ABOUT the entity that created it anyway — it's a catalog
+    // entry shared across whatever gets assigned it. If a tenant ever names a
+    // tag after a real person, the fix is renaming or deleting that tag, not
+    // wiring it to a subject key.
+    name: createTextField({
+      required: true,
+      maxLength: 64,
+      sortable: true,
+      searchable: true,
+      personal: false,
+      reason: "catalog_label",
+    }),
+    // Optional UI hint (hex or token). No enforcement — purely for rendering.
+    color: createTextField({ maxLength: 32, personal: false, reason: "technical_reference" }),
+    // 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, personal: false, reason: "technical_reference" }),
+  },
+});
+
+// tag-assignment — host-agnostic join row keyed by (entityType, entityId). This
+// is the event-sourced, feature-owned projection that replaces a relational
+// pivot+JOIN: the framework projects `read_tag_assignments` from this entity's
+// own CRUD events, so tagging needs NO column on the host entity.
+//
+// The assignment's aggregate-id is derived deterministically from
+// (tenantId, tagId, entityType, entityId) — see aggregate-id.ts — so there is
+// exactly one row per (tag, entity) and assign is idempotent.
+//
+// softDelete is required, NOT cosmetic: the aggregate-id is deterministic, so
+// removing a tag leaves a (created+deleted) event stream behind under that id.
+// A hard delete would force the next assign to create() at version 0 onto that
+// existing stream → version_conflict (the same tag could never be re-attached).
+// With softDelete the assign handler resurrects the stream via restore(); the
+// list query filters isDeleted, so removed assignments stay hidden.
+//
+// Cross-entity views compose in the read-layer (no JOIN):
+//   - tags of an entity   → list assignments filter { field: "entityId", op: "eq" }
+//   - entities with a tag  → list assignments filter { field: "tagId",   op: "eq" }
+export function createTagAssignmentEntity(
+  access?: EntityDefinition["access"],
+  parents?: readonly string[],
+) {
+  return createEntity({
+    table: "read_tag_assignments",
+    description:
+      "The join row recording that one catalog tag is attached to one host entity, addressed by tagId, entityType and entityId, with exactly one row per pair. An entity may carry many tags, unlike the single-folder membership rows.",
+    softDelete: true,
+    access,
+    // Declared unconditionally: the host-visibility gate is the default for
+    // both paths, and `parents` only narrows which hosts are admissible.
+    parentRef: {
+      entityTypeField: "entityType",
+      entityIdField: "entityId",
+      ...(parents !== undefined && { allowedTypes: parents }),
+    },
+    fields: {
+      tagId: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      entityType: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+      entityId: createTextField({
+        required: true,
+        maxLength: 128,
+        personal: false,
+        reason: "technical_reference",
+      }),
+    },
+  });
+}
+
+export const tagAssignmentEntity = createTagAssignmentEntity();

package/packages/bundled-features/src/tags/executor.ts

@@ -0,0 +1,24 @@
+import { createEntityExecutor, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createTagAssignmentEntity, tagAssignmentEntity, tagEntity } from "./entity.js";
+
+// Shared executors for the tag + tag-assignment write-handlers.
+// createEntityExecutor is side-effect-free; instantiating once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: tagExecutor } = createEntityExecutor("tag", tagEntity);
+export const { executor: tagAssignmentExecutor } = createEntityExecutor(
+  "tag-assignment",
+  tagAssignmentEntity,
+);
+
+// Carries only `ownership.write`: the executor enforces entity.access.write on
+// create/restore/delete, while a read rule would hide rows from the handlers'
+// own idempotency reads and the delete-tag cascade.
+export function createTagAssignmentExecutor(
+  ownership: EntityDefinition["access"] | undefined,
+): typeof tagAssignmentExecutor {
+  if (ownership?.write === undefined) return tagAssignmentExecutor;
+  return createEntityExecutor(
+    "tag-assignment",
+    createTagAssignmentEntity({ write: ownership.write }),
+  ).executor;
+}

package/packages/bundled-features/src/tags/feature.ts

@@ -0,0 +1,219 @@
+// tags — generic, host-agnostic tagging for ANY entity.
+//
+// **Event-sourced, not relational.** There is no pivot table with foreign keys
+// and JOINs. The feature owns two event-sourced entities:
+//   1. `tag` (read_tags)            — per-tenant tag catalog.
+//   2. `tag-assignment` (read_tag_assignments) — join rows keyed by
+//      (entityType, entityId), with a deterministic aggregate-id so assign is
+//      idempotent. The framework projects both tables from their own CRUD
+//      events; no host column and no hand-written MSP are needed.
+//
+// Cross-entity views compose in the read-layer (no JOIN) by listing
+// tag-assignments filtered on entityId (tags of an entity) or tagId (entities
+// with a tag). See entity.ts.
+//
+// Handlers: create-tag, update-tag (rename/recolor/re-scope), delete-tag
+// (cascades over assignments), assign-tag, remove-tag, list tags, list assignments.
+// Convention aliases tag:{create,update,delete} + tag:detail back the
+// entityList/entityEdit catalog screens (legacy QNs stay for TagManager).
+// Deferred: optional host-projection decoration (`wireTagsFor`), search indexing.
+
+import {
+  type AccessRule,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type EntityDefinition,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared/index.js";
+import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants.js";
+import { createTagAssignmentEntity, tagEntity } from "./entity.js";
+import { createTagAssignmentExecutor } from "./executor.js";
+import { createAssignTagHandler } from "./handlers/assign-tag.write.js";
+import { createCreateTagHandler } from "./handlers/create-tag.write.js";
+import { createDeleteTagHandler } from "./handlers/delete-tag.write.js";
+import { createRemoveTagHandler } from "./handlers/remove-tag.write.js";
+import { createUpdateTagHandler } from "./handlers/update-tag.write.js";
+import { TAGS_FEATURE_I18N } from "./i18n.js";
+import { createTagEditScreen, createTagListScreen } from "./screens.js";
+
+// 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
+// (handlers, queries, hooks) on/off per tenant — no host-side hook. `default`
+// is the enablement when no toggle row / tier override exists. For a tier-gated
+// feature use { default: false } (fail-closed) and list the feature name in the
+// entitling tiers' TierMap; tenants below it get every tag path disabled.
+type TagsToggleable = { readonly default: boolean };
+
+function registerTags(
+  r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>,
+  access: AccessRule,
+  toggleable: TagsToggleable | undefined,
+  ownership: EntityDefinition["access"] | undefined,
+  parents: readonly string[] | undefined,
+): void {
+  r.describe(
+    "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. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `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: { reason } } }) 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",
+    category: "data",
+    recommended: false,
+  });
+
+  // Tier-gating is a framework concern, not a per-app hook: declaring the
+  // feature toggleable lets tier-engine/feature-toggles cut it per tenant.
+  if (toggleable !== undefined) r.toggleable(toggleable);
+
+  const tagAssignmentEntity = createTagAssignmentEntity(ownership, parents);
+  r.entity("tag", tagEntity);
+  r.entity("tag-assignment", tagAssignmentEntity);
+
+  r.writeHandler(createCreateTagHandler(access));
+  r.writeHandler(createUpdateTagHandler(access));
+  r.writeHandler(createDeleteTagHandler(access));
+  const assignmentExecutor = createTagAssignmentExecutor(ownership);
+  r.writeHandler(createAssignTagHandler(access, assignmentExecutor));
+  r.writeHandler(createRemoveTagHandler(access, assignmentExecutor));
+
+  // Convention aliases for entityList/entityEdit — create stays flat-payload
+  // (payloadMode=values); update must accept the {id,version,changes} envelope
+  // entityEdit sends (legacy update-tag stays for TagManager). delete stays
+  // legacy so assignment cascade is preserved (convention delete would orphan).
+  r.writeHandler({
+    ...createCreateTagHandler(access, "tag:create"),
+    description:
+      "Adds a tag to the caller's tenant tag catalog and mints its id; this is the convention name the declarative tag catalog screens dispatch, with the same effect as the legacy create-tag.",
+  });
+  r.writeHandler(
+    defineEntityUpdateHandler("tag", tagEntity, {
+      access,
+      description:
+        "Renames, recolours or re-scopes a catalog tag from the entity-edit `{ id, version, changes }` envelope; this is the convention name the tag edit screen submits, unlike the flat-payload legacy update-tag.",
+    }),
+  );
+  r.writeHandler({
+    ...createDeleteTagHandler(access, "tag:delete"),
+    description:
+      "Deletes a catalog tag and detaches it from every entity carrying it; this is the convention name the tag catalog list screen's delete row-action dispatches, with the same cascade as the legacy delete-tag.",
+    agent: { risk: "high" },
+  });
+
+  r.queryHandler(
+    defineEntityListHandler("tag", tagEntity, {
+      access,
+      description:
+        "Lists the caller's tenant tag catalog with each tag's name, colour and scope; use it to render the catalog or to offer a user the tags they can attach.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityListHandler("tag-assignment", tagAssignmentEntity, {
+      access,
+      description:
+        "Lists the tag-to-entity assignment rows of the caller's tenant; filter on entityId to get one record's tags, or on tagId to get every record carrying a tag.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("tag", tagEntity, {
+      access,
+      description:
+        "Reads one catalog tag by id with its name, colour and scope; use it to load a single tag into an edit form rather than to find which entities carry it.",
+    }),
+  );
+
+  // Standalone catalog: entityList + entityEdit. App navs via
+  // r.nav("tags:screen:tag-list"). TagManager stays for picker/section only.
+  r.screen(createTagListScreen(access));
+  r.screen(createTagEditScreen(access));
+  r.translations({ keys: TAGS_FEATURE_I18N });
+}
+
+export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
+  registerTags(r, DEFAULT_TAG_ACCESS, undefined, undefined, undefined),
+);
+
+export type TagsFeatureOptions = {
+  /** Access rule for all tag write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: { reason: "..." } } when the host lets any
+   *  authenticated tenant user tag (like the rest of its handlers), or
+   *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+  /** Make the whole feature tier-gatable: declares r.toggleable so the
+   *  tier-engine/feature-toggles can enable/disable every tag path per tenant.
+   *  `default` applies when no toggle/tier override exists — use { default: false }
+   *  for fail-closed tier-gating. Omit to keep tags always-on (default). */
+  readonly toggleable?: TagsToggleable;
+  /** Row-level ownership on the tag-assignment rows themselves — orthogonal to
+   *  `access`, which only gates whether a caller may dispatch assign/remove/list
+   *  at all. `ownership.read` is no longer what keeps a caller from reading
+   *  assignments on host entities they can't see: that gate is default-on since
+   *  fw#2766 and derives from the entity's `parentRef`. Use `ownership.read` for
+   *  an ADDITIONAL row rule on the assignment row itself; it is AND-ed with the
+   *  host-visibility gate, never a replacement for it. Applies only to
+   *  `tag-assignment`; the `tag` catalog stays tenant-wide by design.
+   *
+   *  `ownership.write` is separate and does NOT affect list/read. It's
+   *  consulted on every assignment write: assign-tag (create/restore),
+   *  remove-tag (delete) and the framework's generic forget path. The
+   *  delete-tag cascade stays ungated, since deleting a catalog tag detaches
+   *  it everywhere. A `from()` rule there also gates GDPR erasure
+   *  (`forget`): if the rule's role map doesn't cover whatever role the
+   *  erasure/retention pipeline runs as, `forget` denies instead of
+   *  crypto-shredding — a silent Art.17 failure, not a thrown error. Make
+   *  sure any `ownership.write` you set covers that role, or leave it unset. */
+  readonly ownership?: EntityDefinition["access"];
+  /** Allowlist narrowing which registered entities may carry a tag. Not what
+   *  turns host-checking on — assign/remove and the assignment list always
+   *  verify that entityType names a registered entity whose row the caller can
+   *  see. Setting it narrows further, and shrinks the read gate's SQL, which
+   *  otherwise considers every registered entity as a candidate host. */
+  readonly parents?: readonly string[];
+};
+
+function resolveAccess(opts: TagsFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_TAG_ACCESS;
+}
+
+// Backwards-compat / options wrapper. Without options returns the module-level
+// singleton (no rebuild). access/roles/toggleable/ownership build a fresh
+// feature-definition.
+export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFeature {
+  if (
+    opts.access === undefined &&
+    opts.roles === undefined &&
+    opts.toggleable === undefined &&
+    opts.ownership === undefined &&
+    opts.parents === undefined
+  ) {
+    return tagsFeature;
+  }
+  if (opts.parents !== undefined && opts.parents.length === 0) {
+    throw new Error(
+      "createTagsFeature({ parents }): parents must not be an empty array — " +
+        "an empty allowlist rejects every assign-tag call and hides every " +
+        "assignment row. Omit `parents` to keep every registered entity " +
+        "admissible as a host instead.",
+    );
+  }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createTagsFeature({ ownership }): ownership.write must not contain a " +
+        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
+        "layer (the read path, via buildOwnershipClause). Write paths that " +
+        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
+        "evaluate them, so such a rule can only ever deny — boot validation " +
+        "rejects it too (fw#2626). Use a `from()` rule for ownership.write, or " +
+        "leave it unset.",
+    );
+  }
+  const access = resolveAccess(opts);
+  return defineFeature(TAGS_FEATURE_NAME, (r) =>
+    registerTags(r, access, opts.toggleable, opts.ownership, opts.parents),
+  );
+}

package/packages/bundled-features/src/tags/handlers/assign-tag.write.ts

@@ -0,0 +1,101 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
+import { tagAssignmentAggregateId } from "../aggregate-id.js";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor, tagExecutor } from "../executor.js";
+import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas.js";
+
+// assign-tag — links a tag to a host entity by (entityType, entityId). The
+// assignment id is deterministic, so the row is unique per (tag, entity).
+//
+// Idempotency over the full lifecycle (assign → remove → assign):
+//   - already active        → return success (requested end state).
+//   - removed (soft-deleted) → restore() the existing stream. create() would
+//     append at version 0 onto the created+deleted stream and version_conflict;
+//     the deterministic id means that stream is permanent.
+//   - never assigned         → create() (restore reports not_found).
+// A concurrent first-time race converges: both callers fall through to
+// create(), the loser's create() version_conflicts, and the handler treats
+// that as success since the winner already wrote the desired end state.
+//
+// Referential integrity: there is no FK (event-sourced, no JOIN), so before a
+// first-time create we verify the tag exists in the catalog — a malformed call
+// with an unknown tagId would otherwise project a dangling assignment.
+//
+// Host reference: entityType/entityId are never trusted client input either —
+// the aggregate-id is tenant-scoped, so this is not a cross-tenant hole, but
+// without the check any dispatch-eligible tenant user could tag an object they
+// are not allowed to read. See shared/parent-visibility.ts.
+export function createAssignTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  assignmentExecutor: typeof tagAssignmentExecutor = tagAssignmentExecutor,
+): WriteHandlerDef {
+  return {
+    name: "assign-tag",
+    schema: assignTagPayloadSchema,
+    access,
+    description:
+      "Attaches an existing catalog tag to one host entity addressed by its type and id, reporting success when the tag was already attached; use it to tag a record, not to create the tag.",
+    handler: async (event, ctx) => {
+      const payload = event.payload as AssignTagPayload; // @cast-boundary engine-payload
+      const denied = await denyUnlessJoinRowParentVisible(
+        ctx.registry,
+        "tag-assignment",
+        payload,
+        event.user,
+        ctx.db,
+      );
+      if (denied) return denied;
+
+      const id = tagAssignmentAggregateId(
+        event.user.tenantId,
+        payload.tagId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const existing = await assignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (existing) {
+        return { isSuccess: true as const, data: { id } };
+      }
+
+      const restored = await assignmentExecutor.restore({ id }, event.user, ctx.db);
+      if (restored.isSuccess) return { isSuccess: true as const, data: { id } };
+      // A concurrent first-time assign can also land here: the other caller's
+      // create() already wrote an active row between our `existing` read
+      // above and this restore() call, so restore() correctly refuses with
+      // "not_deleted" — but the desired end state is already true. Converge
+      // like the create() race below instead of surfacing a spurious error.
+      if ((restored.error.details as { reason?: string } | undefined)?.reason === "not_deleted") {
+        return { isSuccess: true as const, data: { id } };
+      }
+      if (restored.error.code !== "not_found") return restored;
+
+      const tag = await tagExecutor.detail({ id: payload.tagId }, event.user, ctx.db);
+      if (!tag) return writeFailure(new NotFoundError("tag", payload.tagId));
+
+      const created = await assignmentExecutor.create(
+        {
+          id,
+          tagId: payload.tagId,
+          entityType: payload.entityType,
+          entityId: payload.entityId,
+        },
+        event.user,
+        ctx.db,
+      );
+      if (created.isSuccess) return created;
+      // A concurrent first-time assign of the same (tag, entity) races here —
+      // both callers' `existing` read above saw null, so both fall through to
+      // create(). The loser's create() version_conflicts (409), but the
+      // desired end state (the assignment exists) is already true — the
+      // winner just wrote it. Converge instead of surfacing a spurious 409
+      // for an idempotent operation.
+      if (created.error.code !== "version_conflict") return created;
+      return { isSuccess: true as const, data: { id } };
+    },
+  };
+}
+
+export const assignTagHandler: WriteHandlerDef = createAssignTagHandler();

package/packages/bundled-features/src/tags/handlers/create-tag.write.ts

@@ -0,0 +1,27 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagExecutor } from "../executor.js";
+import { type CreateTagPayload, createTagPayloadSchema } from "../schemas.js";
+
+// 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). Editing is update-tag.write.ts; delete (with cascade) is delete-tag.write.ts.
+export function createCreateTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  name = "create-tag",
+): WriteHandlerDef {
+  return {
+    name,
+    schema: createTagPayloadSchema,
+    access,
+    description:
+      "Adds a tag to the caller's tenant tag catalog from a flat payload and mints its id; this is the legacy name the TagManager and TagPicker widgets dispatch, and it does not attach the new tag to anything.",
+    handler: async (event, ctx) => {
+      const payload = event.payload as CreateTagPayload; // @cast-boundary engine-payload
+      return tagExecutor.create(payload, event.user, ctx.db);
+    },
+  };
+}
+
+export const createTagHandler: WriteHandlerDef = createCreateTagHandler();

package/packages/bundled-features/src/tags/handlers/delete-tag.write.ts

@@ -0,0 +1,60 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor, tagExecutor } from "../executor.js";
+import { type DeleteTagPayload, deleteTagPayloadSchema } from "../schemas.js";
+
+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,
+  name = "delete-tag",
+): WriteHandlerDef {
+  return {
+    name,
+    schema: deleteTagPayloadSchema,
+    access,
+    description:
+      "Deletes a catalog tag and cascades a detach over every assignment still carrying it, so the tag disappears from all entities at once; this is the legacy name the TagManager dispatches.",
+    agent: { risk: "high" },
+    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/packages/bundled-features/src/tags/handlers/remove-tag.write.ts

@@ -0,0 +1,53 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
+import { tagAssignmentAggregateId } from "../aggregate-id.js";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor } from "../executor.js";
+import { type RemoveTagPayload, removeTagPayloadSchema } from "../schemas.js";
+
+// remove-tag — unlinks a tag from a host entity. Idempotent: removing an
+// assignment that doesn't exist is already the requested end state (not
+// assigned), so we pre-check and return success without a delete.
+//
+// Host reference: entityType/entityId are client input, so the caller must be
+// able to see the host row before detaching anything from it — see
+// shared/parent-visibility.ts.
+export function createRemoveTagHandler(
+  access: AccessRule = DEFAULT_TAG_ACCESS,
+  assignmentExecutor: typeof tagAssignmentExecutor = tagAssignmentExecutor,
+): WriteHandlerDef {
+  return {
+    name: "remove-tag",
+    schema: removeTagPayloadSchema,
+    access,
+    description:
+      "Detaches one catalog tag from one host entity, reporting success when it was not attached; use it to untag a single record while the tag itself stays in the catalog.",
+    handler: async (event, ctx) => {
+      const payload = event.payload as RemoveTagPayload; // @cast-boundary engine-payload
+      const denied = await denyUnlessJoinRowParentVisible(
+        ctx.registry,
+        "tag-assignment",
+        payload,
+        event.user,
+        ctx.db,
+      );
+      if (denied) return denied;
+
+      const id = tagAssignmentAggregateId(
+        event.user.tenantId,
+        payload.tagId,
+        payload.entityType,
+        payload.entityId,
+      );
+
+      const existing = await assignmentExecutor.detail({ id }, event.user, ctx.db);
+      if (!existing) {
+        return { isSuccess: true as const, data: { id } };
+      }
+
+      return assignmentExecutor.delete({ id }, event.user, ctx.db);
+    },
+  };
+}
+
+export const removeTagHandler: WriteHandlerDef = createRemoveTagHandler();