@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/tags/entity.js

@@ -0,0 +1,87 @@
+import { createEntity, createTextField, } 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, parents) {
+    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/dist/tags/executor.d.ts

@@ -0,0 +1,2 @@
+export declare const tagExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare const tagAssignmentExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;

package/dist/tags/executor.js

@@ -0,0 +1,7 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { 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);

package/dist/tags/feature.d.ts

@@ -0,0 +1,47 @@
+import { type AccessRule, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+type TagsToggleable = {
+    readonly default: boolean;
+};
+export declare const tagsFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};
+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 by the framework's generic delete/forget/restore paths (not by
+     *  this feature's own assign-tag handler — see createTagsFeature's
+     *  boot-guard comment). 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[];
+};
+export declare function createTagsFeature(opts?: TagsFeatureOptions): typeof tagsFeature;
+export {};

package/dist/tags/feature.js

@@ -0,0 +1,121 @@
+// 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 { defineEntityDetailHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, } 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 { 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";
+function registerTags(r, access, toggleable, ownership, parents) {
+    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));
+    r.writeHandler(createAssignTagHandler(access));
+    r.writeHandler(createRemoveTagHandler(access));
+    // 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));
+function resolveAccess(opts) {
+    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 = {}) {
+    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/dist/tags/handlers/assign-tag.write.d.ts

@@ -0,0 +1,3 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createAssignTagHandler(access?: AccessRule): WriteHandlerDef;
+export declare const assignTagHandler: WriteHandlerDef;

package/dist/tags/handlers/assign-tag.write.js

@@ -0,0 +1,86 @@
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { joinRowParentIsVisible } from "../../shared/index.js";
+import { tagAssignmentAggregateId } from "../aggregate-id.js";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor, tagExecutor } from "../executor.js";
+import { 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 = DEFAULT_TAG_ACCESS) {
+    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; // @cast-boundary engine-payload
+            // entityType/entityId are client input: the caller must be able to see
+            // the host row through that entity's own read path (tenant scope plus its
+            // `access.read` ownership) before its assignment row may be written.
+            // Checked FIRST, ahead of every lookup below, so a denied caller can't tell
+            // an invisible parent apart from a missing assignment or an unknown tag —
+            // every path answers with the same NotFoundError.
+            if (!(await joinRowParentIsVisible(ctx.registry, "tag-assignment", payload, event.user, ctx.db))) {
+                return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
+            }
+            const id = tagAssignmentAggregateId(event.user.tenantId, payload.tagId, payload.entityType, payload.entityId);
+            const existing = await tagAssignmentExecutor.detail({ id }, event.user, ctx.db);
+            if (existing) {
+                return { isSuccess: true, data: { id } };
+            }
+            const restored = await tagAssignmentExecutor.restore({ id }, event.user, ctx.db);
+            if (restored.isSuccess)
+                return { isSuccess: true, 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?.reason === "not_deleted") {
+                return { isSuccess: true, 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 tagAssignmentExecutor.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, data: { id } };
+        },
+    };
+}
+export const assignTagHandler = createAssignTagHandler();

package/dist/tags/handlers/create-tag.write.d.ts

@@ -0,0 +1,3 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createCreateTagHandler(access?: AccessRule, name?: string): WriteHandlerDef;
+export declare const createTagHandler: WriteHandlerDef;

package/dist/tags/handlers/create-tag.write.js

@@ -0,0 +1,20 @@
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagExecutor } from "../executor.js";
+import { 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 = DEFAULT_TAG_ACCESS, name = "create-tag") {
+    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; // @cast-boundary engine-payload
+            return tagExecutor.create(payload, event.user, ctx.db);
+        },
+    };
+}
+export const createTagHandler = createCreateTagHandler();

package/dist/tags/handlers/delete-tag.write.d.ts

@@ -0,0 +1,3 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createDeleteTagHandler(access?: AccessRule, name?: string): WriteHandlerDef;
+export declare const deleteTagHandler: WriteHandlerDef;

package/dist/tags/handlers/delete-tag.write.js

@@ -0,0 +1,43 @@
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor, tagExecutor } from "../executor.js";
+import { 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 = DEFAULT_TAG_ACCESS, name = "delete-tag") {
+    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; // @cast-boundary engine-payload
+            const existing = await tagExecutor.detail({ id: payload.id }, event.user, ctx.db);
+            if (!existing) {
+                return { isSuccess: true, 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 = createDeleteTagHandler();

package/dist/tags/handlers/remove-tag.write.d.ts

@@ -0,0 +1,3 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createRemoveTagHandler(access?: AccessRule): WriteHandlerDef;
+export declare const removeTagHandler: WriteHandlerDef;

package/dist/tags/handlers/remove-tag.write.js

@@ -0,0 +1,40 @@
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { joinRowParentIsVisible } from "../../shared/index.js";
+import { tagAssignmentAggregateId } from "../aggregate-id.js";
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagAssignmentExecutor } from "../executor.js";
+import { 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 = DEFAULT_TAG_ACCESS) {
+    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; // @cast-boundary engine-payload
+            // entityType/entityId are client input: the caller must be able to see
+            // the host row through that entity's own read path (tenant scope plus its
+            // `access.read` ownership) before its assignment row may be written.
+            // Checked FIRST, ahead of every lookup below, so a denied caller can't tell
+            // an invisible parent apart from a missing assignment or an unknown tag —
+            // every path answers with the same NotFoundError.
+            if (!(await joinRowParentIsVisible(ctx.registry, "tag-assignment", payload, event.user, ctx.db))) {
+                return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
+            }
+            const id = tagAssignmentAggregateId(event.user.tenantId, payload.tagId, payload.entityType, payload.entityId);
+            const existing = await tagAssignmentExecutor.detail({ id }, event.user, ctx.db);
+            if (!existing) {
+                return { isSuccess: true, data: { id } };
+            }
+            return tagAssignmentExecutor.delete({ id }, event.user, ctx.db);
+        },
+    };
+}
+export const removeTagHandler = createRemoveTagHandler();

package/dist/tags/handlers/update-tag.write.d.ts

@@ -0,0 +1,3 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createUpdateTagHandler(access?: AccessRule, name?: string): WriteHandlerDef;
+export declare const updateTagHandler: WriteHandlerDef;

package/dist/tags/handlers/update-tag.write.js

@@ -0,0 +1,28 @@
+import { DEFAULT_TAG_ACCESS } from "../constants.js";
+import { tagExecutor } from "../executor.js";
+import { updateTagPayloadSchema } from "../schemas.js";
+// 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 = DEFAULT_TAG_ACCESS, name = "update-tag") {
+    return {
+        name,
+        schema: updateTagPayloadSchema,
+        access,
+        description: "Renames, recolours or re-scopes a catalog tag from a flat optimistic-locked payload, leaving omitted fields untouched; this is the legacy name the TagManager dispatches, unlike the entity-edit alias that takes a changes envelope.",
+        handler: async (event, ctx) => {
+            const payload = event.payload; // @cast-boundary engine-payload
+            const changes = {};
+            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 = createUpdateTagHandler();

package/dist/tags/i18n.d.ts

@@ -0,0 +1,5 @@
+type LocalizedString = {
+    readonly en: string;
+};
+export declare const TAGS_FEATURE_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/tags/i18n.js

@@ -0,0 +1,7 @@
+export const TAGS_FEATURE_I18N = {
+    "screen:tag-list.title": { en: "Tags" },
+    "screen:tag-edit.title": { en: "Tag" },
+    "tags:entity:tag:field:name": { en: "Name" },
+    "tags:entity:tag:field:color": { en: "Color" },
+    "tags:entity:tag:field:scope": { en: "Scope" },
+};

package/dist/tags/index.d.ts

@@ -0,0 +1,11 @@
+export { tagAssignmentAggregateId } from "./aggregate-id.js";
+export { DEFAULT_TAG_ACCESS, DEFAULT_TAG_ROLES, TAGS_COLUMN_RENDERER_NAME, TAGS_EDIT_SCREEN_ID, TAGS_FEATURE_NAME, TAGS_FILTER_EXTENSION_NAME, TAGS_SCREEN_ID, TAGS_SECTION_EXTENSION_NAME, TagsHandlers, TagsQueries, } from "./constants.js";
+export { tagAssignmentEntity, tagEntity } from "./entity.js";
+export { createTagsFeature, type TagsFeatureOptions, tagsFeature } from "./feature.js";
+export { assignTagHandler, createAssignTagHandler, } from "./handlers/assign-tag.write.js";
+export { createCreateTagHandler, createTagHandler, } from "./handlers/create-tag.write.js";
+export { createDeleteTagHandler, deleteTagHandler, } from "./handlers/delete-tag.write.js";
+export { createRemoveTagHandler, removeTagHandler, } from "./handlers/remove-tag.write.js";
+export { createUpdateTagHandler, updateTagHandler, } from "./handlers/update-tag.write.js";
+export { type AssignTagPayload, assignTagPayloadSchema, type CreateTagPayload, createTagPayloadSchema, type DeleteTagPayload, deleteTagPayloadSchema, type RemoveTagPayload, removeTagPayloadSchema, type UpdateTagPayload, updateTagPayloadSchema, } from "./schemas.js";
+export { createTagEditScreen, createTagListScreen } from "./screens.js";

package/dist/tags/index.js

@@ -0,0 +1,11 @@
+export { tagAssignmentAggregateId } from "./aggregate-id.js";
+export { DEFAULT_TAG_ACCESS, DEFAULT_TAG_ROLES, TAGS_COLUMN_RENDERER_NAME, TAGS_EDIT_SCREEN_ID, TAGS_FEATURE_NAME, TAGS_FILTER_EXTENSION_NAME, TAGS_SCREEN_ID, TAGS_SECTION_EXTENSION_NAME, TagsHandlers, TagsQueries, } from "./constants.js";
+export { tagAssignmentEntity, tagEntity } from "./entity.js";
+export { createTagsFeature, tagsFeature } from "./feature.js";
+export { assignTagHandler, createAssignTagHandler, } from "./handlers/assign-tag.write.js";
+export { createCreateTagHandler, createTagHandler, } from "./handlers/create-tag.write.js";
+export { createDeleteTagHandler, deleteTagHandler, } from "./handlers/delete-tag.write.js";
+export { createRemoveTagHandler, removeTagHandler, } from "./handlers/remove-tag.write.js";
+export { createUpdateTagHandler, updateTagHandler, } from "./handlers/update-tag.write.js";
+export { assignTagPayloadSchema, createTagPayloadSchema, deleteTagPayloadSchema, removeTagPayloadSchema, updateTagPayloadSchema, } from "./schemas.js";
+export { createTagEditScreen, createTagListScreen } from "./screens.js";

package/dist/tags/schemas.d.ts

@@ -0,0 +1,31 @@
+import * as z from "zod";
+export declare const createTagPayloadSchema: z.ZodObject<{
+    name: z.ZodString;
+    color: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateTagPayload = z.infer<typeof createTagPayloadSchema>;
+export declare const updateTagPayloadSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateTagPayload = z.infer<typeof updateTagPayloadSchema>;
+export declare const deleteTagPayloadSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type DeleteTagPayload = z.infer<typeof deleteTagPayloadSchema>;
+export declare const assignTagPayloadSchema: z.ZodObject<{
+    tagId: z.ZodString;
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+}, z.core.$strip>;
+export type AssignTagPayload = z.infer<typeof assignTagPayloadSchema>;
+export declare const removeTagPayloadSchema: z.ZodObject<{
+    tagId: z.ZodString;
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+}, z.core.$strip>;
+export type RemoveTagPayload = z.infer<typeof removeTagPayloadSchema>;