@cosmicdrift/kumiko-bundled-features 0.88.0 → 0.90.0

package/src/data-retention/run-retention-cleanup.ts

@@ -0,0 +1,151 @@
+// Retention-Cleanup-Runner (S2.D2b) — pure Function, vom retention-cleanup-Cron
+// pro fan-out-Tenant aufgerufen.
+//
+// Iteriert alle implicit-Entity-Projektionen, loest pro Entity die effektive
+// Retention-Policy (3-Schicht-Resolver, siehe resolver.ts) und wendet die
+// Strategy auf Rows an deren reference-Timestamp aelter als der keepFor-Cutoff
+// ist:
+//
+//   - hardDelete  → deleteManyBatched (selbst-begrenzt, kein Full-Table-Scan)
+//   - softDelete  → isDeleted=true/deletedAt=now, nur auf noch-nicht-geloeschte
+//   - anonymize   → DEFERRED (siehe unten)
+//   - blockDelete → ignoriert (Aufbewahrungs-Pflicht; user-forget loest anonymize)
+//
+// **Schaerfer als soft-delete-cleanup:** dieser Cron hardDeleted LIVE Rows
+// (keyed auf reference, Default createdAt), nicht bereits-soft-geloeschte.
+// Darum die Spalten-Existenz-Pruefung vor jedem WHERE — eine fehlende/vertippte
+// reference-Spalte wuerde sonst ein malformed/all-matching WHERE ergeben und
+// pauschal loeschen.
+//
+// **anonymize deferred:** anonymize behaelt die Row. Ohne Idempotenz-Marker
+// wuerde der taegliche UPDATE jede past-cutoff Row endlos neu treffen — genau
+// der Full-Table-Scan den die Strategie vermeiden soll (hardDelete begrenzt
+// sich selbst, softDelete via isDeleted:false). Kein bundled-Entity nutzt
+// zeitgesteuertes anonymize; der user-forget-Flow (run-forget-cleanup) deckt
+// anonymize keyed auf userId ab. Follow-up fuer den Marker.
+
+import { deleteManyBatched, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner, WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { computeCutoff, type Instant } from "./keep-for";
+import type { RetentionPresetKey } from "./presets";
+import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant";
+
+const DEFAULT_BATCH_LIMIT = 1000;
+const DEFAULT_REFERENCE_FIELD = "createdAt";
+
+// Der Boot-Validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
+// erlaubt diese Aliase als retention.reference, auch wenn sie nicht in
+// entity.fields deklariert sind — die physischen Spalten heissen aber anders
+// (table-builder.ts: inserted_at/modified_at). Hier zur Cleanup-Zeit auf das
+// echte Entity-Feld mappen, sonst trifft die Spalten-Existenz-Pruefung unten
+// und der Cron wuerde lautlos nichts tun. deletedAt/lastSeenAt sind echte
+// Felder (softDelete bzw. session) und brauchen keine Uebersetzung.
+const FRAMEWORK_REFERENCE_ALIAS: Readonly<Record<string, string>> = {
+  createdAt: "insertedAt",
+  updatedAt: "modifiedAt",
+};
+
+export interface RunRetentionCleanupArgs {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+  /** Layer-2 Preset (aus resolveTenantRetentionPreset). null = nur Layer 1/3. */
+  readonly tenantPreset: RetentionPresetKey | null;
+  /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+  readonly now: Instant;
+  readonly batchLimit?: number;
+}
+
+export interface RetentionCleanupSkip {
+  readonly entityName: string;
+  readonly reason: "missing_reference_column" | "missing_softdelete_columns";
+}
+
+export interface RunRetentionCleanupResult {
+  readonly hardDeleted: number;
+  readonly softDeleted: number;
+  /** Entities mit anonymize-Strategy — deferred (Header). Cron logt sie. */
+  readonly anonymizeDeferred: readonly string[];
+  /** Anomalien: Policy referenziert eine Spalte die die Tabelle nicht hat. */
+  readonly skipped: readonly RetentionCleanupSkip[];
+}
+
+export async function runRetentionCleanup(
+  args: RunRetentionCleanupArgs,
+): Promise<RunRetentionCleanupResult> {
+  const { db, registry, tenantId, tenantPreset, now } = args;
+  const batchLimit = args.batchLimit ?? DEFAULT_BATCH_LIMIT;
+
+  let hardDeleted = 0;
+  let softDeleted = 0;
+  const anonymizeDeferred: string[] = [];
+  const skipped: RetentionCleanupSkip[] = [];
+
+  for (const proj of registry.getAllProjections().values()) {
+    // Nur implicit-Entity-Projektionen mit Tabelle — wie soft-delete-cleanup.
+    // Custom-Projektionen + unmanaged-Tables (z.B. sessions) sind kein Target.
+    if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
+    const entityName = proj.source;
+
+    const resolved = await resolveRetentionPolicyForTenant({
+      db,
+      registry,
+      tenantId,
+      entityName,
+      tenantPreset,
+    });
+    const policy = resolved.policy;
+    if (!policy) continue;
+
+    const table = proj.table as Record<string, unknown>; // @cast-boundary column-presence probe
+    const declaredReference = policy.reference ?? DEFAULT_REFERENCE_FIELD;
+    const referenceField = FRAMEWORK_REFERENCE_ALIAS[declaredReference] ?? declaredReference;
+
+    if (table[referenceField] === undefined) {
+      skipped.push({ entityName, reason: "missing_reference_column" });
+      continue;
+    }
+
+    const cutoff = computeCutoff(policy.keepFor, now);
+    const where: WhereObject = { [referenceField]: { lt: cutoff } };
+    // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
+    // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
+    // anderen treffen.
+    if (table["tenantId"] !== undefined) {
+      where["tenantId"] = tenantId;
+    }
+
+    switch (policy.strategy) {
+      case "hardDelete": {
+        const res = await deleteManyBatched(db, proj.table, where, { limit: batchLimit });
+        hardDeleted += res.deleted;
+        break;
+      }
+      case "softDelete": {
+        if (table["isDeleted"] === undefined || table["deletedAt"] === undefined) {
+          skipped.push({ entityName, reason: "missing_softdelete_columns" });
+          break;
+        }
+        const updated = await updateMany(
+          db,
+          proj.table,
+          { isDeleted: true, deletedAt: now },
+          { ...where, isDeleted: false },
+        );
+        softDeleted += updated.length;
+        break;
+      }
+      case "anonymize": {
+        anonymizeDeferred.push(entityName);
+        break;
+      }
+      case "blockDelete": {
+        // skip: Aufbewahrungs-Pflicht — Cleanup ignoriert, user-forget anonymisiert
+        break;
+      }
+    }
+  }
+
+  return { hardDeleted, softDeleted, anonymizeDeferred, skipped };
+}

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);
+}