@cosmicdrift/kumiko-bundled-features 0.89.0 → 0.90.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.89.0",
+  "version": "0.90.2",
   "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>",
@@ -32,6 +32,9 @@
     "./custom-fields/web": "./src/custom-fields/web/index.ts",
     "./tags": "./src/tags/index.ts",
     "./tags/web": "./src/tags/web/index.ts",
+    "./folders": "./src/folders/index.ts",
+    "./folders/web": "./src/folders/web/index.ts",
+    "./folders-user-data": "./src/folders-user-data/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
@@ -86,11 +89,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.89.0",
-    "@cosmicdrift/kumiko-framework": "0.89.0",
-    "@cosmicdrift/kumiko-headless": "0.89.0",
-    "@cosmicdrift/kumiko-renderer": "0.89.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.89.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.90.2",
+    "@cosmicdrift/kumiko-framework": "0.90.2",
+    "@cosmicdrift/kumiko-headless": "0.90.2",
+    "@cosmicdrift/kumiko-renderer": "0.90.2",
+    "@cosmicdrift/kumiko-renderer-web": "0.90.2",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/folders/__tests__/drift.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { folderAssignmentAggregateId } from "../aggregate-id";
+
+// Drift-Pin-Tests — these values are cross-boot contracts. If they go red:
+// stop, think, revert. aggregate-id.ts names this file.
+
+const TENANT = "00000000-0000-0000-0000-000000000001";
+
+describe("folders drift pins", () => {
+  test("folder-assignment aggregate-id namespace is stable across boots", () => {
+    // FOLDER_ASSIGNMENT_NAMESPACE is in stone — changing it re-keys every
+    // existing assignment stream and breaks event-replay. If this fails: revert
+    // the namespace, do not adjust the expected values.
+    const base = folderAssignmentAggregateId(TENANT, "credit", "c-1");
+
+    expect(base).toBe(folderAssignmentAggregateId(TENANT, "credit", "c-1")); // deterministic
+    // folderId is NOT part of the key (single-membership): every OTHER tuple
+    // component is, with no collisions across the axes.
+    expect(base).not.toBe(
+      folderAssignmentAggregateId("11111111-1111-1111-1111-111111111111", "credit", "c-1"),
+    );
+    expect(base).not.toBe(folderAssignmentAggregateId(TENANT, "invoice", "c-1"));
+    expect(base).not.toBe(folderAssignmentAggregateId(TENANT, "credit", "c-2"));
+
+    // Pinned actual outputs — the drift-detector for the namespace constant.
+    expect(base).toBe("a57e2be6-1831-5d08-9e83-2de64578de6d");
+    expect(
+      folderAssignmentAggregateId("11111111-1111-1111-1111-111111111111", "credit", "c-1"),
+    ).toBe("d2153ce9-5ffa-544e-b850-a4a7fefa7d89");
+    expect(folderAssignmentAggregateId(TENANT, "invoice", "c-1")).toBe(
+      "7c849492-a806-5e73-a824-e90dfc761e3a",
+    );
+    expect(folderAssignmentAggregateId(TENANT, "credit", "c-2")).toBe(
+      "d9ad71bc-78db-5588-9f61-b77f35229ed3",
+    );
+  });
+
+  test("aggregate-id format is a valid uuid", () => {
+    expect(folderAssignmentAggregateId(TENANT, "credit", "c-1")).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+});

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

@@ -0,0 +1,168 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_FOLDER_ROLES } from "../constants";
+import { createFoldersFeature } from "../feature";
+import { clearFolderPayloadSchema, setFolderPayloadSchema } from "../schemas";
+
+// Unit tests: feature-shape, role-options, schema-validation. The ES-loop
+// behaviour (single-membership set/move/clear, projection, tenant-isolation,
+// read composition) needs a real stack → folders.integration.test.ts.
+
+function writeAccess(
+  feature: ReturnType<typeof createFoldersFeature>,
+  nameMatch: string,
+): readonly string[] {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  const access = entry[1].access;
+  if (!access || !("roles" in access)) throw new Error(`handler ${nameMatch} has no roles`);
+  return access.roles;
+}
+
+function queryAccess(
+  feature: ReturnType<typeof createFoldersFeature>,
+  nameMatch: string,
+): readonly string[] {
+  const entry = Object.entries(feature.queryHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`query ${nameMatch} not registered`);
+  const access = entry[1].access;
+  if (!access || !("roles" in access)) throw new Error(`query ${nameMatch} has no roles`);
+  return access.roles;
+}
+
+function rawWriteAccess(
+  feature: ReturnType<typeof createFoldersFeature>,
+  nameMatch: string,
+): unknown {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  return entry[1].access;
+}
+
+describe("createFoldersFeature shape", () => {
+  test("registers folder + folder-assignment entities, 5 write-handlers, 3 query-handlers", () => {
+    const feature = createFoldersFeature();
+
+    expect(Object.keys(feature.entities ?? {})).toEqual(
+      expect.arrayContaining(["folder", "folder-assignment"]),
+    );
+
+    expect(Object.keys(feature.writeHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/folder:create/),
+        expect.stringMatching(/folder:update/),
+        expect.stringMatching(/folder:delete/),
+        expect.stringMatching(/set-folder/),
+        expect.stringMatching(/clear-folder/),
+      ]),
+    );
+    expect(Object.keys(feature.writeHandlers)).toHaveLength(5);
+
+    expect(Object.keys(feature.queryHandlers)).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/folder:list/),
+        expect.stringMatching(/folder:detail/),
+        expect.stringMatching(/folder-assignment:list/),
+      ]),
+    );
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(3);
+  });
+});
+
+describe("createFoldersFeature access-options", () => {
+  test("without options: singleton with default roles on every path", () => {
+    const feature = createFoldersFeature();
+    expect(feature).toBe(createFoldersFeature());
+    for (const path of [
+      "folder:create",
+      "folder:update",
+      "folder:delete",
+      "set-folder",
+      "clear-folder",
+    ]) {
+      expect(writeAccess(feature, path)).toEqual([...DEFAULT_FOLDER_ROLES]);
+    }
+    expect(queryAccess(feature, "folder:list")).toEqual([...DEFAULT_FOLDER_ROLES]);
+    expect(queryAccess(feature, "folder-assignment:list")).toEqual([...DEFAULT_FOLDER_ROLES]);
+  });
+
+  test("roles option overrides every write- and query-path", () => {
+    const feature = createFoldersFeature({ roles: ["Admin", "Editor"] });
+    expect(writeAccess(feature, "set-folder")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "folder:create")).toEqual(["Admin", "Editor"]);
+    expect(queryAccess(feature, "folder:list")).toEqual(["Admin", "Editor"]);
+  });
+
+  test("access:{openToAll} applies to every write- and query-path", () => {
+    const feature = createFoldersFeature({ access: { openToAll: true } });
+    for (const path of [
+      "folder:create",
+      "folder:update",
+      "folder:delete",
+      "set-folder",
+      "clear-folder",
+    ]) {
+      expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
+    }
+  });
+
+  test("access takes precedence over the roles shorthand", () => {
+    const feature = createFoldersFeature({ access: { openToAll: true }, roles: ["Admin"] });
+    expect(rawWriteAccess(feature, "set-folder")).toEqual({ openToAll: true });
+  });
+});
+
+describe("createFoldersFeature toggleable-option (tier-gating)", () => {
+  test("without toggleable: feature is always-on (toggleableDefault undefined)", () => {
+    expect(createFoldersFeature().toggleableDefault).toBeUndefined();
+  });
+
+  test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
+    const feature = createFoldersFeature({
+      access: { openToAll: true },
+      toggleable: { default: false },
+    });
+    expect(feature.toggleableDefault).toBe(false);
+  });
+
+  test("toggleable alone (no access/roles) builds a fresh, non-singleton feature", () => {
+    const feature = createFoldersFeature({ toggleable: { default: false } });
+    expect(feature).not.toBe(createFoldersFeature());
+    expect(writeAccess(feature, "folder:create")).toEqual([...DEFAULT_FOLDER_ROLES]);
+  });
+});
+
+describe("setFolderPayloadSchema", () => {
+  const valid = { folderId: "f-1", entityType: "credit", entityId: "c-1" };
+
+  test("accepts a full (folder, entity) reference", () => {
+    expect(setFolderPayloadSchema.safeParse(valid).success).toBe(true);
+  });
+
+  test("rejects missing folderId", () => {
+    expect(
+      setFolderPayloadSchema.safeParse({ entityType: "credit", entityId: "c-1" }).success,
+    ).toBe(false);
+  });
+
+  test("rejects empty folderId", () => {
+    expect(setFolderPayloadSchema.safeParse({ ...valid, folderId: "" }).success).toBe(false);
+  });
+
+  test("rejects entityId over 128 chars", () => {
+    expect(setFolderPayloadSchema.safeParse({ ...valid, entityId: "x".repeat(129) }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("clearFolderPayloadSchema", () => {
+  test("accepts an entity reference (no folderId)", () => {
+    expect(
+      clearFolderPayloadSchema.safeParse({ entityType: "credit", entityId: "c-1" }).success,
+    ).toBe(true);
+  });
+
+  test("rejects missing entityId", () => {
+    expect(clearFolderPayloadSchema.safeParse({ entityType: "credit" }).success).toBe(false);
+  });
+});

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

@@ -0,0 +1,290 @@
+// Full-stack integration for the folders bundle. Drives create → set → list →
+// move → clear through the real dispatcher + entity-projection + DB. Proves the
+// architecture end-to-end WITHOUT any host wiring (folders are host-agnostic —
+// the host is just the entityType/entityId strings on the assignment):
+//   - create-folder projects into read_folders (incl. nested parentId)
+//   - set-folder projects a SINGLE membership row keyed by (entityType, entityId)
+//   - re-setting to a different folder MOVES the entity (still one row) — the
+//     defining difference from tags' many-to-many
+//   - clear-folder unfiles; set → clear → set resurrects the deterministic stream
+//   - referential integrity (unknown folderId rejected) + multi-tenant isolation
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { FoldersHandlers, FoldersQueries } from "../constants";
+import { folderAssignmentEntity, folderEntity } from "../entity";
+import { createFoldersFeature } from "../feature";
+
+const foldersFeature = createFoldersFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [foldersFeature] });
+  await unsafeCreateEntityTable(stack.db, folderEntity);
+  await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_folders");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_folder_assignments");
+});
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const otherTenant = createTestUser({
+  roles: ["TenantAdmin"],
+  tenantId: "00000000-0000-4000-8000-0000000000aa",
+});
+
+async function createFolder(name: string, parentId?: string, user = admin): Promise<string> {
+  const payload = parentId === undefined ? { name } : { name, parentId };
+  const folder = await stack.http.writeOk<{ id: string }>(
+    FoldersHandlers.createFolder,
+    payload,
+    user,
+  );
+  return folder.id;
+}
+
+async function setFolder(folderId: string, entityId: string, user = admin) {
+  return stack.http.writeOk(
+    FoldersHandlers.setFolder,
+    { folderId, entityType: "credit", entityId },
+    user,
+  );
+}
+
+async function clearFolder(entityId: string, user = admin) {
+  return stack.http.writeOk(FoldersHandlers.clearFolder, { entityType: "credit", entityId }, user);
+}
+
+async function listFolders(user = admin): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    FoldersQueries.folderList,
+    {},
+    user,
+  );
+  return res.rows;
+}
+
+async function assignmentsOf(
+  entityId: string,
+  user = admin,
+): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    FoldersQueries.assignmentList,
+    { filter: { field: "entityId", op: "eq", value: entityId } },
+    user,
+  );
+  return res.rows;
+}
+
+// Active assignments only — clear soft-deletes (the stream is kept so a re-set
+// can restore it), so isDeleted=true rows must not count as filed.
+async function countAssignments(tenantId: string): Promise<number> {
+  const rows = await asRawClient(stack.db).unsafe(
+    "SELECT count(*)::int AS n FROM read_folder_assignments WHERE tenant_id = $1 AND is_deleted = FALSE",
+    [tenantId],
+  );
+  return (rows as ReadonlyArray<{ n: number }>)[0]?.n ?? 0;
+}
+
+describe("folders integration — catalog (tree)", () => {
+  test("create-folder lands in read_folders", async () => {
+    const id = await createFolder("Immobilie Berlin");
+    const folders = await listFolders();
+    expect(folders).toHaveLength(1);
+    expect(folders[0]?.["id"]).toBe(id);
+    expect(folders[0]?.["name"]).toBe("Immobilie Berlin");
+    expect(folders[0]?.["parentId"]).toBeNull();
+  });
+
+  test("create-folder with parentId nests under the parent", async () => {
+    const root = await createFolder("Immobilie Berlin");
+    const child = await createFolder("Person Müller", root);
+    const folders = await listFolders();
+    expect(folders).toHaveLength(2);
+    const childRow = folders.find((f) => f["id"] === child);
+    expect(childRow?.["parentId"]).toBe(root);
+  });
+});
+
+describe("folders integration — single-membership set / move / clear", () => {
+  test("set-folder files an entity; assignment is queryable", async () => {
+    const f = await createFolder("Gruppe A");
+    await setFolder(f, "credit-1");
+
+    const rows = await assignmentsOf("credit-1");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["folderId"]).toBe(f);
+    expect(rows[0]?.["entityType"]).toBe("credit");
+  });
+
+  test("re-setting to a different folder MOVES (still exactly one row)", async () => {
+    const a = await createFolder("A");
+    const b = await createFolder("B");
+    await setFolder(a, "credit-1");
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+
+    await setFolder(b, "credit-1"); // MOVE, not a second assignment
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    const rows = await assignmentsOf("credit-1");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["folderId"]).toBe(b);
+  });
+
+  test("set the same folder twice is an idempotent no-op (one row)", async () => {
+    const f = await createFolder("dup");
+    await setFolder(f, "credit-2");
+    await setFolder(f, "credit-2");
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+  });
+
+  test("clear-folder unfiles the entity", async () => {
+    const f = await createFolder("temp");
+    await setFolder(f, "credit-3");
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+
+    await clearFolder("credit-3");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+    expect(await assignmentsOf("credit-3")).toHaveLength(0);
+  });
+
+  test("clearing a never-filed entity succeeds (idempotent end-state)", async () => {
+    await clearFolder("credit-never");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+  });
+
+  test("set → clear → set resurrects the same deterministic stream", async () => {
+    const f = await createFolder("recurring");
+    await setFolder(f, "credit-r");
+    await clearFolder("credit-r");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+
+    await setFolder(f, "credit-r"); // restore, not 409
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    expect((await assignmentsOf("credit-r"))[0]?.["folderId"]).toBe(f);
+  });
+
+  test("set → clear → set into a DIFFERENT folder lands in the new folder", async () => {
+    const a = await createFolder("A");
+    const b = await createFolder("B");
+    await setFolder(a, "credit-x");
+    await clearFolder("credit-x");
+    await setFolder(b, "credit-x"); // restore + update folderId to b
+    const rows = await assignmentsOf("credit-x");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["folderId"]).toBe(b);
+  });
+});
+
+describe("folders integration — rename via folder:update", () => {
+  test("update renames, optimistic-locked, bumps version", async () => {
+    const id = await createFolder("Alt");
+    const before = (await listFolders()).find((f) => f["id"] === id);
+    const version = before?.["version"] as number;
+    expect(typeof version).toBe("number");
+
+    await stack.http.writeOk(
+      FoldersHandlers.updateFolder,
+      { id, version, changes: { name: "Neu" } },
+      admin,
+    );
+    const after = (await listFolders()).find((f) => f["id"] === id);
+    expect(after?.["name"]).toBe("Neu");
+    expect(after?.["version"]).toBe(version + 1);
+  });
+});
+
+describe("folders integration — referential integrity", () => {
+  test("set-folder with an unknown folderId is rejected (no dangling assignment)", async () => {
+    const err = await stack.http.writeErr(
+      FoldersHandlers.setFolder,
+      { folderId: "00000000-0000-4000-8000-00000000dead", entityType: "credit", entityId: "c-y" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(404);
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+  });
+});
+
+describe("folders integration — multi-tenant isolation", () => {
+  test("tenant B sees neither tenant A's folders nor assignments", async () => {
+    const f = await createFolder("A-only", undefined, admin);
+    await setFolder(f, "credit-8", admin);
+
+    expect(await listFolders(otherTenant)).toHaveLength(0);
+    expect(await assignmentsOf("credit-8", otherTenant)).toHaveLength(0);
+
+    expect(await listFolders(admin)).toHaveLength(1);
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    expect(await countAssignments(otherTenant.tenantId)).toBe(0);
+  });
+});
+
+// The access option must reach the runtime: a host mounting folders with
+// openToAll lets a user WITHOUT any default folder role file freely (the exact
+// failure that bit money-horse, whose signup users carry "Admin").
+describe("folders integration — openToAll access model", () => {
+  let openStack: TestStack;
+  const unprivileged = createTestUser({ roles: ["Viewer"] });
+
+  beforeAll(async () => {
+    openStack = await setupTestStack({
+      features: [createFoldersFeature({ access: { openToAll: true } })],
+    });
+    await unsafeCreateEntityTable(openStack.db, folderEntity);
+    await unsafeCreateEntityTable(openStack.db, folderAssignmentEntity);
+    await createEventsTable(openStack.db);
+  });
+
+  afterAll(async () => {
+    await openStack.cleanup();
+  });
+
+  test("a non-folder-role user can create, set, list and clear", async () => {
+    const folder = await openStack.http.writeOk<{ id: string }>(
+      FoldersHandlers.createFolder,
+      { name: "Ordner A" },
+      unprivileged,
+    );
+    await openStack.http.writeOk(
+      FoldersHandlers.setFolder,
+      { folderId: folder.id, entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+    const folders = await openStack.http.queryOk<{ rows: unknown[] }>(
+      FoldersQueries.folderList,
+      {},
+      unprivileged,
+    );
+    expect(folders.rows).toHaveLength(1);
+    await openStack.http.writeOk(
+      FoldersHandlers.clearFolder,
+      { entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+  });
+
+  test("the SAME user is denied on a default-role-mounted feature", async () => {
+    const denied = await stack.http.writeErr(
+      FoldersHandlers.createFolder,
+      { name: "nope" },
+      unprivileged,
+    );
+    expect(denied.httpStatus).toBe(403);
+  });
+});

package/src/folders/aggregate-id.ts

@@ -0,0 +1,23 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID namespace for folder-assignment aggregate-id derivation. Frozen:
+// changing it would re-key every existing assignment stream → broken replay.
+// Drift-pinned in __tests__.
+const FOLDER_ASSIGNMENT_NAMESPACE = "b2e1f4a7-3c9d-4e8b-a1f6-5d2c8b3e7a9f";
+
+/**
+ * Deterministic aggregate-id for a folder-assignment from the tuple
+ * (tenantId, entityType, entityId) — note: NO folderId. Exactly one aggregate
+ * exists per (tenant, entity), so an entity belongs to at most one folder;
+ * re-assigning to a different folder updates the same stream (move) instead of
+ * creating a second row. This is the single-membership counterpart to tags'
+ * many-to-many aggregate-id (which includes the tagId).
+ */
+// @wrapper-known uuid-domain
+export function folderAssignmentAggregateId(
+  tenantId: string,
+  entityType: string,
+  entityId: string,
+): string {
+  return uuidv5(`${tenantId}|${entityType}|${entityId}`, FOLDER_ASSIGNMENT_NAMESPACE);
+}

package/src/folders/constants.ts

@@ -0,0 +1,40 @@
+// @runtime client
+// folders bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/folders-feature.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const FOLDERS_FEATURE_NAME = "folders";
+
+// Registry name for the drop-in <FolderSection> component. Apps reference it in a
+// screen schema via `component: { react: { __component: FOLDER_SECTION_EXTENSION_NAME } }`
+// after mounting foldersClient(); the component is also importable directly for
+// standalone use from `@cosmicdrift/kumiko-bundled-features/folders/web`.
+export const FOLDER_SECTION_EXTENSION_NAME = "FolderSection";
+
+// Qualified handler names (QN format: scope:type:name). The folder catalog uses
+// generic defineEntity*Handler (create/update/delete) → "folder:<verb>" qualified
+// to "folders:write:folder:<verb>". update covers rename (and, later, reparent).
+// set-folder/clear-folder are the hand-written single-membership handlers.
+export const FoldersHandlers = {
+  createFolder: "folders:write:folder:create",
+  updateFolder: "folders:write:folder:update",
+  deleteFolder: "folders:write:folder:delete",
+  setFolder: "folders:write:set-folder",
+  clearFolder: "folders:write:clear-folder",
+} as const;
+
+export const FoldersQueries = {
+  folderList: "folders:query:folder:list",
+  folderDetail: "folders:query:folder:detail",
+  assignmentList: "folders:query:folder-assignment:list",
+} as const;
+
+// Default RBAC for every folder write/read path. Like tags, folders are a
+// low-sensitivity organisation tool, so both tenant roles may use them. Apps
+// with their own role vocabulary override via createFoldersFeature({ roles }),
+// or adopt the host's access model with createFoldersFeature({ access }).
+export const DEFAULT_FOLDER_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+export const DEFAULT_FOLDER_ACCESS: AccessRule = { roles: DEFAULT_FOLDER_ROLES };

package/src/folders/entity.ts

@@ -0,0 +1,42 @@
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+// folder — per-tenant hierarchical catalog. Event-sourced (create/update/delete
+// via the standard executor); the framework projects `read_folders` from its own
+// CRUD events. `parentId` null → root folder; otherwise it points at another
+// folder's id, forming a tree. tenantId is a base column set by the framework →
+// tenant-scoped.
+export const folderEntity = createEntity({
+  table: "read_folders",
+  fields: {
+    name: createTextField({ required: true, maxLength: 64 }),
+    // Parent folder id, or absent for a root folder. No FK (event-sourced); a
+    // dangling parentId renders the folder at root — folders-view guards cycles.
+    parentId: createTextField({ maxLength: 64 }),
+  },
+});
+
+// folder-assignment — host-agnostic membership row keyed by (entityType, entityId).
+// Unlike tag-assignment this is SINGLE-membership: the aggregate-id is derived from
+// (tenantId, entityType, entityId) WITHOUT folderId (see aggregate-id.ts), so an
+// entity has exactly one assignment row and "put into folder X" updates folderId
+// (move) instead of creating a second row.
+//
+// softDelete is required, NOT cosmetic: the aggregate-id is deterministic, so
+// clearing an assignment leaves a (created+deleted) event stream under that id.
+// A hard delete would force the next set to create() at version 0 onto that
+// existing stream → version_conflict. With softDelete the set handler resurrects
+// the stream via restore(); the list query filters isDeleted.
+//
+// Cross-entity views compose in the read-layer (no JOIN):
+//   - folder of an entity  → list assignments filter { field: "entityId", op: "eq" }
+//   - entities in a folder  → list assignments filter { field: "folderId", op: "eq" }
+export const folderAssignmentEntity = createEntity({
+  table: "read_folder_assignments",
+  softDelete: true,
+  fields: {
+    folderId: createTextField({ required: true, maxLength: 64 }),
+    entityType: createTextField({ required: true, maxLength: 64 }),
+    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+    entityId: createTextField({ required: true, maxLength: 128 }),
+  },
+});

package/src/folders/executor.ts

@@ -0,0 +1,11 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { folderAssignmentEntity, folderEntity } from "./entity";
+
+// Shared executors for the folder + folder-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: folderExecutor } = createEntityExecutor("folder", folderEntity);
+export const { executor: folderAssignmentExecutor } = createEntityExecutor(
+  "folder-assignment",
+  folderAssignmentEntity,
+);