@cosmicdrift/kumiko-bundled-features 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -26,6 +26,7 @@
     "./tier-engine": "./src/tier-engine/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",
     "./custom-fields": "./src/custom-fields/index.ts",
+    "./custom-fields/web": "./src/custom-fields/web/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",

package/src/custom-fields/__tests__/custom-fields.integration.test.ts

@@ -335,6 +335,64 @@ describe("custom-fields integration — value validation (Builder-Reuse)", () =>
     expect(await countSetEvents(id)).toBe(0);
   });
 
+  test("required-text accepts empty + over-maxLength strings (constraint-keys stripped)", async () => {
+    const id = "bbbbbbbb-bbbb-4000-8000-00000000000b";
+    // serializedField carries required + maxLength + format — value-schema
+    // strips these before fieldToZod, so the runtime schema collapses to a
+    // bare z.string(). Required-on-set + length/format-enforcement remain
+    // out-of-scope (Plan-Doc "Stammfeld-Identität").
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "note",
+        serializedField: { type: "text", required: true, maxLength: 5, format: "email" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    await createProperty(id, "TypeOnly");
+
+    await setCustomField("property", id, "note", "");
+    await setCustomField("property", id, "note", "not-an-email-and-way-too-long");
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await rawCustomFields(id)).toMatchObject({ note: "not-an-email-and-way-too-long" });
+  });
+
+  test("default-having field validates as plain type (default-key stripped)", async () => {
+    const id = "cccccccc-cccc-4000-8000-00000000000c";
+    // Pre-fix: fieldToZod folded `default` into `.default(...)`. Combined with
+    // emitting `payload.value` (not `parsed.data`) the in-code path would skip
+    // the type-check for a missing value. value-schema now strips `default`
+    // before fieldToZod so the runtime schema is bare `z.number()` — matching
+    // values still pass, type-mismatches still 422.
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "score",
+        serializedField: { type: "number", default: 0 },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    await createProperty(id, "DefaultStripped");
+
+    const err = await setErr(id, "score", "not-a-number");
+    expect(err.httpStatus).toBe(422);
+    expect(err.details).toMatchObject({ reason: "custom_field_value_invalid" });
+    expect(await countSetEvents(id)).toBe(0);
+
+    await setCustomField("property", id, "score", 7);
+    await stack.eventDispatcher?.runOnce();
+    expect(await rawCustomFields(id)).toMatchObject({ score: 7 });
+  });
+
   test("embedded field rejects a non-object value → 422, no event", async () => {
     const id = "aaaaaaaa-aaaa-4000-8000-00000000000a";
     // embedded carries a sub-field schema in serializedField — exercises

package/src/custom-fields/constants.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // custom-fields bundle constants — feature-name + event-names.
 //
 // Spec: kumiko-platform/docs/plans/features/custom-fields.md
@@ -5,6 +6,28 @@
 
 export const CUSTOM_FIELDS_FEATURE_NAME = "custom-fields";
 
+// Qualified handler names (QN format: scope:type:name). Mirror text-
+// content's Handler/Queries object pattern — Clients (z.B. die
+// CustomFieldsFormSection web-component) referenzieren über das Object
+// statt magic-strings.
+export const CustomFieldsHandlers = {
+  defineTenantField: "custom-fields:write:define-tenant-field",
+  defineSystemField: "custom-fields:write:define-system-field",
+  deleteTenantField: "custom-fields:write:delete-tenant-field",
+  deleteSystemField: "custom-fields:write:delete-system-field",
+  setCustomField: "custom-fields:write:set-custom-field",
+  clearCustomField: "custom-fields:write:clear-custom-field",
+} as const;
+
+export const CustomFieldsQueries = {
+  fieldDefinitionList: "custom-fields:query:field-definition:list",
+} as const;
+
+// Name unter dem die web-component im ExtensionSectionsProvider
+// registriert wird — Apps referenzieren ihn im Screen-Schema via
+// `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`.
+export const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
+
 // Event-Type-Names (qualified at registration via r.defineEvent — final
 // names are `custom-fields:event:field-definition-created` etc.).
 // Short-names MUST be in kebab-case (no dots): qualifyEntityName runs toKebab

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -32,11 +32,15 @@ export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 //   3. Value-Validation (Builder-Reuse): der Wert wird gegen das aus
 //      serializedField rehydrierte fieldToZod-Schema geparst. Type-Mismatch →
 //      422, KEIN Event entsteht (Projection bleibt typed — Plan-Doc
-//      Stammfeld-Identität). `value: null` auf einem typisierten Feld ist ein
-//      Type-Mismatch → 422; zum Entfernen eines Werts dient clear-custom-field.
+//      Stammfeld-Identität). `value: null` ODER `value: undefined` auf einem
+//      typisierten Feld sind Type-Mismatches → 422; zum Entfernen eines Werts
+//      dient clear-custom-field.
 //
-// Scope: NUR Type-Validation. Required-on-set + Default-Application sind
-// out-of-scope (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
+// Scope: ECHTE type-only Validation. value-schema.ts strippt `required`,
+// `maxLength`, `format` und `default` aus dem serializedField bevor fieldToZod
+// daraus ein Schema baut — wir prüfen nur die Type-Shape. Required-on-set,
+// Default-Application und Length-/Format-Enforcement bleiben out-of-scope
+// (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
 export const setCustomFieldHandler: WriteHandlerDef = {
   name: "set-custom-field",
   schema: setCustomFieldPayloadSchema,

package/src/custom-fields/lib/value-schema.ts

@@ -4,29 +4,67 @@ import {
   fieldToZod,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { z } from "zod";
+import { SUPPORTED_FIELD_TYPES } from "../constants";
 
 // Builds a Zod schema that validates a custom-field VALUE against its
 // fieldDefinition. Reuses the framework's `fieldToZod` (Builder-Reuse /
 // Stammfeld-Identität, Plan-Doc) — one field-type-schema source, no drift
 // between Stammfeld- and Custom-Field-validation.
 //
+// Scope: type-shape only. fieldToZod also folds `required`, `maxLength`,
+// `format`, and `default` into Zod refinements; we strip those before the
+// call so set-custom-field rejects type-mismatches and only type-mismatches.
+// Required-on-set, default-application, and length/format-enforcement remain
+// out-of-scope per the Plan-Doc ("Stammfeld-Identität" lists them as
+// separate concerns).
+//
 // Vocabulary bridge: custom-fields expose `enum` (Plan + `r.field.enum([...])`)
 // where the framework's FieldDefinition calls the equivalent type `select`
-// with an `options` array. This single boundary translates it; everything
-// else is already FieldDefinition-shaped (the serialized dehydrated builder).
+// with an `options` array.
 //
 // Returns `null` when the serialized field is unparseable or names a type
-// `fieldToZod` cannot interpret — callers then skip value-validation rather
-// than hard-rejecting a field they cannot understand.
+// outside the custom-fields-supported set — callers then skip value-validation.
+
+const SUPPORTED_TYPES_SET: ReadonlySet<string> = new Set(SUPPORTED_FIELD_TYPES);
+const SUPPORTED_EMBEDDED_SUB_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "number",
+  "boolean",
+  "date",
+]);
+
+// Constraint-keys fieldToZod converts into Zod refinements. Stripped so the
+// resulting schema validates the type-shape only, not the constraint.
+const CONSTRAINT_KEYS = ["required", "maxLength", "format", "default"] as const;
+
 export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny | null {
   if (!parsedField || typeof parsedField !== "object") return null;
   const obj = parsedField as Record<string, unknown>;
-  if (typeof obj["type"] !== "string") return null;
+  const rawType = obj["type"];
+  if (typeof rawType !== "string") return null;
+  if (!SUPPORTED_TYPES_SET.has(rawType)) return null;
 
-  const fieldDef =
-    obj["type"] === "enum"
-      ? { ...obj, type: "select", options: obj["values"] ?? obj["options"] ?? [] }
-      : obj;
+  // Embedded sub-fields: pre-check the sub-type set so we surface unknown
+  // sub-types as "skip validation" (return null) rather than letting
+  // fieldToZod's assertUnreachable throw and the catch swallow real bugs.
+  if (rawType === "embedded") {
+    const schema = obj["schema"];
+    if (!schema || typeof schema !== "object") return null;
+    for (const sub of Object.values(schema)) {
+      if (!sub || typeof sub !== "object") return null;
+      const subType = (sub as Record<string, unknown>)["type"];
+      if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
+        return null;
+      }
+    }
+  }
+
+  const fieldDef: Record<string, unknown> = { ...obj };
+  for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
+  if (rawType === "enum") {
+    fieldDef["type"] = "select";
+    fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];
+  }
 
   // fieldToZod's money case validates `currency` against the passed list, not
   // a field-level key — so surface the field's own currency when it declares
@@ -34,12 +72,8 @@ export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny
   const currencies =
     typeof obj["currency"] === "string" ? [obj["currency"] as string] : DEFAULT_CURRENCIES;
 
-  try {
-    // @cast-boundary serialized-field is the dehydrated r.field.X() output =
-    // a FieldDefinition; fieldToZod reads only its type-specific keys (the
-    // extra fieldAccess/sensitive/retention/label keys are ignored).
-    return fieldToZod(fieldDef as unknown as FieldDefinition, currencies);
-  } catch {
-    return null;
-  }
+  // @cast-boundary serialized-field is the dehydrated r.field.X() output =
+  // a FieldDefinition; fieldToZod reads only its type-specific keys (the
+  // extra fieldAccess/sensitive/retention/label keys are ignored).
+  return fieldToZod(fieldDef as unknown as FieldDefinition, currencies);
 }

package/src/custom-fields/web/__tests__/custom-fields-form-section.test.tsx

@@ -0,0 +1,144 @@
+import { describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CustomFieldsFormSection } from "../custom-fields-form-section";
+
+type FieldRow = {
+  id: string;
+  entityName: string;
+  fieldKey: string;
+  type: string;
+  required: boolean;
+  displayOrder: number;
+};
+
+const dispatchSpy = mock(async () => ({ isSuccess: true, data: undefined }));
+let mockedQueryRows: readonly FieldRow[] = [];
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useDispatcher: mock(() => ({
+    write: dispatchSpy,
+    query: mock(),
+    batch: mock(),
+  })),
+  useQuery: mock(() => ({
+    data: { rows: mockedQueryRows },
+    loading: false,
+    error: null,
+    refetch: mock(),
+  })),
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("CustomFieldsFormSection", () => {
+  test("renders an input per matching fieldDefinition and dispatches set-custom-field on save", async () => {
+    mockedQueryRows = [
+      {
+        id: "f1",
+        entityName: "component",
+        fieldKey: "vendor",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+      {
+        id: "f2",
+        entityName: "component",
+        fieldKey: "tier",
+        type: "number",
+        required: false,
+        displayOrder: 2,
+      },
+      {
+        id: "f3",
+        entityName: "incident",
+        fieldKey: "rootCause",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+    dispatchSpy.mockClear();
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    // Only `component`-entity fields are rendered (incident's rootCause filtered out).
+    expect(screen.getByTestId("custom-fields-form-section")).toBeTruthy();
+    const vendorInput = document.getElementById("custom-field-vendor") as HTMLInputElement;
+    const tierInput = document.getElementById("custom-field-tier") as HTMLInputElement;
+    expect(vendorInput).toBeTruthy();
+    expect(tierInput).toBeTruthy();
+    expect(document.getElementById("custom-field-rootCause")).toBeNull();
+
+    // Type in vendor; tier left empty (should be skipped on save).
+    fireEvent.change(vendorInput, { target: { value: "Hetzner" } });
+
+    const saveBtn = screen.getByTestId("custom-fields-form-save");
+    fireEvent.click(saveBtn);
+    // Wait one microtask for the async handleSave loop.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:set-custom-field", {
+      entityName: "component",
+      entityId: "row-42",
+      fieldKey: "vendor",
+      value: "Hetzner",
+    });
+  });
+
+  test("shows create-mode banner when entityId is null", () => {
+    mockedQueryRows = [];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId={null} />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("custom-fields-form-create-mode")).toBeTruthy();
+    expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+  });
+
+  test("shows empty banner when no fieldDefinitions match entityName", () => {
+    mockedQueryRows = [
+      {
+        id: "f3",
+        entityName: "incident",
+        fieldKey: "rootCause",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("custom-fields-form-empty")).toBeTruthy();
+    expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+  });
+});

package/src/custom-fields/web/client-plugin.tsx

@@ -0,0 +1,25 @@
+// @runtime client
+// Client-Feature-Factory für custom-fields. Wird vom App-Code in
+// createKumikoApp({ clientFeatures: [customFieldsClient()] }) eingehängt
+// und registriert die CustomFieldsFormSection unter dem Namen
+// CUSTOM_FIELDS_FORM_EXTENSION_NAME im ExtensionSectionsProvider. Apps
+// referenzieren den Namen im Screen-Schema:
+//
+//   layout: { sections: [
+//     { kind: "extension", title: "...", component: {
+//       react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME }
+//     } },
+//   ]}
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { CUSTOM_FIELDS_FEATURE_NAME, CUSTOM_FIELDS_FORM_EXTENSION_NAME } from "../constants";
+import { CustomFieldsFormSection } from "./custom-fields-form-section";
+
+export function customFieldsClient(): ClientFeatureDefinition {
+  return {
+    name: CUSTOM_FIELDS_FEATURE_NAME,
+    extensionSectionComponents: {
+      [CUSTOM_FIELDS_FORM_EXTENSION_NAME]: CustomFieldsFormSection,
+    },
+  };
+}

package/src/custom-fields/web/custom-fields-form-section.tsx

@@ -0,0 +1,181 @@
+// @runtime client
+// CustomFieldsFormSection — extension-section component für entityEdit-
+// Screens. Lädt die fieldDefinition-Liste des Tenants, filtert auf die
+// host-Entity, rendert pro Definition einen typed Input, dispatched
+// `custom-fields:write:set-custom-field` pro non-empty Value beim Save.
+//
+// Mount via createKumikoApp({ clientFeatures: [customFieldsClient()] })
+// — der clientFeature-Factory registriert diese Component unter dem
+// Namen `CustomFieldsFormSection`, den die App im Screen-Schema via
+// `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`
+// referenziert.
+
+import { useDispatcher, usePrimitives, useQuery } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { CustomFieldsHandlers, CustomFieldsQueries } from "../constants";
+
+type FieldDefinitionRow = {
+  readonly id: string;
+  readonly entityName: string;
+  readonly fieldKey: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly displayOrder: number;
+};
+
+type FieldDefinitionListResponse = {
+  readonly rows: readonly FieldDefinitionRow[];
+};
+
+export function CustomFieldsFormSection({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const { Banner, Button, Field, Input, Text } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const query = useQuery<FieldDefinitionListResponse>(CustomFieldsQueries.fieldDefinitionList, {});
+  const [pending, setPending] = useState<Readonly<Record<string, string>>>({});
+  const [saving, setSaving] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  if (entityId === null) {
+    return (
+      <Banner variant="info" testId="custom-fields-form-create-mode">
+        <Text>Save the entity first to add custom field values.</Text>
+      </Banner>
+    );
+  }
+  if (query.loading && query.data === null) {
+    return (
+      <Banner variant="loading" testId="custom-fields-form-loading">
+        <Text>Loading…</Text>
+      </Banner>
+    );
+  }
+  if (query.error) {
+    return (
+      <Banner variant="error" testId="custom-fields-form-error">
+        <Text>{query.error.i18nKey}</Text>
+      </Banner>
+    );
+  }
+
+  const matchingFields = (query.data?.rows ?? [])
+    .filter((f) => f.entityName === entityName)
+    .slice()
+    .sort((a, b) => a.displayOrder - b.displayOrder);
+
+  if (matchingFields.length === 0) {
+    return (
+      <Banner variant="info" testId="custom-fields-form-empty">
+        <Text>No custom fields defined for "{entityName}".</Text>
+      </Banner>
+    );
+  }
+
+  const handleSave = async (): Promise<void> => {
+    setSaving(true);
+    setErrorKey(null);
+    try {
+      for (const field of matchingFields) {
+        const raw = pending[field.fieldKey];
+        if (raw === undefined || raw === "") continue;
+        const value = coerceValue(field.type, raw);
+        const result = await dispatcher.write(CustomFieldsHandlers.setCustomField, {
+          entityName,
+          entityId,
+          fieldKey: field.fieldKey,
+          value,
+        });
+        if (!result.isSuccess) {
+          setErrorKey(result.error?.i18nKey ?? "custom-fields:save-failed");
+          return;
+        }
+      }
+      setPending({});
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const dirty = Object.values(pending).some((v) => v !== "");
+
+  return (
+    <div data-testid="custom-fields-form-section">
+      {matchingFields.map((field) => (
+        <Field
+          key={field.id}
+          id={`custom-field-${field.fieldKey}`}
+          label={field.fieldKey}
+          required={field.required}
+        >
+          {renderInputFor(field, pending[field.fieldKey] ?? "", (v) =>
+            setPending((p) => ({ ...p, [field.fieldKey]: v })),
+          )}
+        </Field>
+      ))}
+      <Button
+        variant="primary"
+        onClick={() => void handleSave()}
+        disabled={saving || !dirty}
+        testId="custom-fields-form-save"
+      >
+        {saving ? "Saving…" : "Save custom fields"}
+      </Button>
+      {errorKey !== null && (
+        <Banner variant="error" testId="custom-fields-form-save-error">
+          <Text>{errorKey}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+
+  function renderInputFor(
+    field: FieldDefinitionRow,
+    raw: string,
+    onChange: (v: string) => void,
+  ): ReactNode {
+    const id = `custom-field-${field.fieldKey}`;
+    const name = field.fieldKey;
+    if (field.type === "number") {
+      return (
+        <Input
+          kind="number"
+          id={id}
+          name={name}
+          value={raw === "" ? "" : Number(raw)}
+          onChange={(v) => onChange(v === undefined ? "" : String(v))}
+        />
+      );
+    }
+    if (field.type === "boolean") {
+      return (
+        <Input
+          kind="boolean"
+          id={id}
+          name={name}
+          value={raw === "true"}
+          onChange={(v) => onChange(v ? "true" : "false")}
+        />
+      );
+    }
+    if (field.type === "date") {
+      return (
+        <Input kind="date" id={id} name={name} value={raw} onChange={(v) => onChange(v ?? "")} />
+      );
+    }
+    return <Input kind="text" id={id} name={name} value={raw} onChange={onChange} />;
+  }
+}
+
+function coerceValue(type: string, raw: string): unknown {
+  if (type === "number") {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  }
+  if (type === "boolean") return raw === "true";
+  return raw;
+}

package/src/custom-fields/web/index.ts

@@ -0,0 +1,8 @@
+// @runtime client
+export {
+  CUSTOM_FIELDS_FORM_EXTENSION_NAME,
+  CustomFieldsHandlers,
+  CustomFieldsQueries,
+} from "../constants";
+export { customFieldsClient } from "./client-plugin";
+export { CustomFieldsFormSection } from "./custom-fields-form-section";

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

@@ -4,13 +4,11 @@
 //   1. Feature-Definition Smoke (Boot-Validation passes)
 //   2. Cross-Feature-Behavior: fileRef-Entity ist als Hook-Anker für
 //      Sprint-2-userData-Extension nutzbar
-//   3. DDL-Konsistenz: Framework-pgTable + Feature-Entity zeigen auf
-//      dieselbe Postgres-Struktur (Drift-Guard)
-//   4. Event-QN-Match: r.defineEvent + framework's fileUploadedEvent
-//      resolven zum selben QN
+//   3. DDL-Konsistenz: fileRefsTable (buildEntityTable) + fileRefEntity
+//      zeigen auf dieselbe Postgres-Struktur (Drift-Guard)
 
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
-import { FILE_UPLOADED_EVENT_TYPE, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
 
 // Native dialect exposes column metadata on the `columns` array (EntityTableMeta)
@@ -148,21 +146,3 @@ describe("files :: DDL-Konsistenz (M3, S1.7)", () => {
     expect(pgColumns.has("size")).toBe(true);
   });
 });
-
-describe("files :: event-QN-match (M4, S1.7)", () => {
-  test("framework's fileUploadedEvent.name === 'files:event:uploaded'", () => {
-    // Wenn das Framework den Event-Namen aendert, fliegt dieser Test
-    // sofort an — und der QN aus r.defineEvent("uploaded") im feature
-    // wuerde nicht mehr matchen. Drift-Guard.
-    expect(FILE_UPLOADED_EVENT_TYPE).toBe("files:event:uploaded");
-  });
-
-  test("Feature-Name 'files' + Event-Short 'uploaded' = QN 'files:event:uploaded'", () => {
-    // r.defineEvent("uploaded") in defineFeature("files", ...) resolved
-    // zu QN "files:event:uploaded" via Framework-Convention. Match
-    // garantiert dass framework's appendEvent + EventDef-Schema-
-    // Validation auf demselben QN landen.
-    const expected = `${feature.name}:event:uploaded`;
-    expect(expected).toBe(FILE_UPLOADED_EVENT_TYPE);
-  });
-});

package/src/files/feature.ts

@@ -1,34 +1,7 @@
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { fileUploadedPayloadSchema } from "@cosmicdrift/kumiko-framework/files";
-import { fileRefEntity } from "./schema/file-ref";
-
-export { fileRefEntity } from "./schema/file-ref";
-
-// files — Schema-Sicht der framework-internen file_refs-Tabelle als
-// bundled-feature, damit Cross-Feature-Hooks (userData, tenantData) sich
-// an die "fileRef"-Entity hängen können.
-//
-// Sprint 1.5 (this commit):
-//   - r.entity("fileRef", fileRefEntity) — Schema-Surface
-//   - r.defineEvent("uploaded", schema)  — Event-Marker
-//
-// Sprint 2 (kommt):
-//   - r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
-//
-// Sprint 5 (kommt):
-//   - r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
-//
-// Routes bleiben framework-internal (multipart-Upload + binary-Streaming
-// passen nicht in das Handler-Pattern; siehe schema/file-ref.ts für
-// Architektur-Note).
-//
-// Sprint-1.5-Plan-Roadmap-Wille: "fileRefsTable bleibt in framework
-// (kein Daten-Move), aber r.entity('fileRef') deklariert sie für das
-// Feature." — diese Datei IST die Umsetzung.
-export function createFilesFeature(): FeatureDefinition {
-  return defineFeature("files", (r) => {
-    r.entity("fileRef", fileRefEntity);
-
-    r.defineEvent("uploaded", fileUploadedPayloadSchema);
-  });
-}
+// files — full Event-Sourcing für File-Metadata. Die Implementierung (Entity,
+// files:event:*-Events, Inline-Projektion) lebt seit dem ES-Umbau im
+// Framework neben file-routes + fileRefsTable, weil file-routes hart davon
+// abhängt (appendDomainEventCore verlangt registrierte Events + Projektion).
+// Dieses Modul re-exportiert nur, damit der App-Import-Pfad
+// `@cosmicdrift/kumiko-bundled-features/files` stabil bleibt.
+export { createFilesFeature, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";

package/src/files-provider-s3/__tests__/s3-provider.integration.test.ts

@@ -110,6 +110,33 @@ describe("s3-provider (Minio)", () => {
     const key = uniqueKey("never-existed.bin");
     await expect(provider.read(key)).rejects.toThrow();
   });
+
+  test("writeStream round-trip via multipart writer preserves bytes", async () => {
+    // Pinst die idiomatic Bun-S3-writer-Form (write + end, kein manual
+    // flush). Chunks summieren absichtlich auf > 5 MiB (partSize) UND auf
+    // einen krummen Rest, damit der multipart-finalizer auch dann greift,
+    // wenn die Source-Chunks nicht auf die Part-Boundary aufgehen.
+    const key = uniqueKey("stream-multipart.bin");
+    const partSize = 5 * 1024 * 1024;
+    const chunk = new Uint8Array(1024 * 1024);
+    for (let i = 0; i < chunk.length; i++) chunk[i] = i % 251;
+    const chunks: Uint8Array[] = [];
+    for (let i = 0; i < 7; i++) chunks.push(chunk);
+
+    if (!provider.writeStream) throw new Error("s3 provider should implement writeStream");
+    await provider.writeStream(
+      key,
+      (async function* () {
+        for (const c of chunks) yield c;
+      })(),
+    );
+
+    const readBack = await provider.read(key);
+    expect(readBack.byteLength).toBe(chunks.length * chunk.length);
+    expect(readBack.byteLength).toBeGreaterThan(partSize);
+    expect(readBack[0]).toBe(0);
+    expect(readBack[readBack.byteLength - 1]).toBe(chunk[chunk.length - 1]);
+  });
 });
 
 describe("createS3ProviderFromEnv", () => {

package/src/files-provider-s3/s3-provider.ts

@@ -72,26 +72,21 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
     },
 
     async writeStream(key, source, options): Promise<void> {
-      // Echtes multipart-streaming via Bun's S3-Writer — der Source-
-      // AsyncIterable wird chunk-weise hochgeladen, niemals alles im Memory.
-      // Wir flushen sobald ein Part voll ist, damit der Heap-Footprint auf
-      // ~ein Part begrenzt bleibt, unabhaengig von der Total-Bundle-Size —
-      // macht 1GB+ Exports ohne OOM moeglich.
+      // Echtes multipart-streaming via Bun's S3-Writer — partSize steuert die
+      // Part-Boundary intern (AWS/R2 verlangen non-final Parts >= 5 MiB,
+      // sonst EntityTooSmall beim CompleteMultipartUpload). Manuelles flush()
+      // hier wuerde genau diese Garantie brechen, sobald die Source-Chunks
+      // nicht auf partSize aufgehen.
       const writer = client.file(key).writer({
         ...(options?.mimeType !== undefined && { type: options.mimeType }),
         retry: 3,
         queueSize: 4,
         partSize: STREAM_PART_SIZE,
       });
-      let buffered = 0;
       for await (const chunk of source) {
-        // write() returns a Promise when the writer applies backpressure —
-        // awaiting it bounds the in-flight queue instead of buffering ahead.
-        buffered += await writer.write(chunk);
-        if (buffered >= STREAM_PART_SIZE) {
-          await writer.flush();
-          buffered = 0;
-        }
+        // Await applies Backpressure und bounded die in-flight Queue auf
+        // queueSize, statt unbegrenzt zu puffern.
+        await writer.write(chunk);
       }
       await writer.end();
     },

package/src/user-data-rights/__tests__/cross-data-matrix.integration.test.ts

@@ -25,6 +25,7 @@ import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
@@ -145,21 +146,9 @@ beforeAll(async () => {
       UNIQUE(user_id, tenant_id)
     )
   `);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS file_refs (
-      id UUID PRIMARY KEY,
-      tenant_id UUID NOT NULL,
-      storage_key TEXT NOT NULL,
-      file_name TEXT NOT NULL,
-      mime_type TEXT NOT NULL,
-      size INTEGER NOT NULL,
-      entity_type TEXT,
-      entity_id TEXT,
-      field_name TEXT,
-      inserted_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-      inserted_by_id TEXT
-    )
-  `);
+  // fileRef ist buildEntityTable-getrieben (softDelete) — echte Entity-Tabelle
+  // pushen statt hand-CREATE, damit is_deleted/deleted_at/deleted_by_id da sind.
+  await unsafePushTables(stack.db, { fileRefsTable });
   await asRawClient(stack.db).unsafe(`
     CREATE TABLE IF NOT EXISTS test_notes (
       id UUID PRIMARY KEY,

package/src/user-data-rights/__tests__/file-retention.integration.test.ts

@@ -0,0 +1,231 @@
+// File-Retention Integration-Test.
+//
+// Beweist, dass die BESTEHENDE data-retention + Forget-Pipeline auch für
+// `fileRef` greift — kein file-spezifischer Retention-Mechanismus. fileRef ist
+// ein normales softDelete-ES-Entity; sein Forget-/Retention-Verhalten kommt
+// aus genau derselben Kette wie bei jedem anderen Entity:
+//
+//   runForgetCleanup → resolveRetentionPolicyForTenant(entityName="fileRef")
+//   → policyToStrategy → fileRef userData delete-Hook (delete | anonymize)
+//
+// Abgedeckt:
+//   1. Default (keine Override-Policy) → Forget HARD-löscht die Datei (Art. 17).
+//   2. Tenant-Retention-Override fileRef→anonymize → Forget anonymisiert
+//      (insertedById=null, Row bleibt) statt zu löschen.
+//   3. Per-Tenant: derselbe User, anonymize in Tenant A, delete in Tenant B —
+//      die Policy entscheidet pro Tenant.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { tenantRetentionOverrideTable } from "../../data-retention/schema/tenant-retention-override";
+import { createFilesFeature } from "../../files";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { createUserDataRightsFeature } from "../feature";
+import { runForgetCleanup } from "../run-forget-cleanup";
+
+let stack: TestStack;
+let db: DbConnection;
+
+const TENANT_A = "00000000-0000-4000-8000-00000000000a";
+const TENANT_B = "00000000-0000-4000-8000-00000000000b";
+const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+
+function uuid(suffix: number): string {
+  return `aaaaaaaa-aaaa-4aaa-8aaa-${suffix.toString(16).padStart(12, "0")}`;
+}
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+const NOW = (): Instant => getTemporal().Now.instant();
+function pastInstant(): Instant {
+  return getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
+}
+
+let overrideExecutor: ReturnType<typeof createEventStoreExecutor>;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createFilesFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createSessionsFeature(),
+      createUserDataRightsFeature(),
+      createUserDataRightsDefaultsFeature(),
+    ],
+  });
+  db = stack.db;
+
+  await unsafeCreateEntityTable(db, userEntity);
+  await unsafeCreateEntityTable(db, tenantRetentionOverrideEntity);
+  await unsafePushTables(db, { fileRefsTable });
+  await asRawClient(db).unsafe(`
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      tenant_id UUID NOT NULL,
+      user_id TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      inserted_by_id TEXT,
+      modified_by_id TEXT,
+      is_deleted BOOLEAN NOT NULL DEFAULT false,
+      deleted_at TIMESTAMPTZ,
+      deleted_by_id TEXT,
+      roles TEXT NOT NULL DEFAULT '[]',
+      UNIQUE(user_id, tenant_id)
+    )
+  `);
+
+  overrideExecutor = createEventStoreExecutor(
+    tenantRetentionOverrideTable,
+    tenantRetentionOverrideEntity,
+    { entityName: "tenant-retention-override" },
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(db, [
+    userTable,
+    "read_tenant_memberships",
+    fileRefsTable,
+    tenantRetentionOverrideTable,
+  ]);
+});
+
+async function seedForgetUser(id: string): Promise<void> {
+  await insertOne(db, userTable, {
+    id,
+    tenantId: TENANT_SYSTEM,
+    email: `user-${id}@example.com`,
+    passwordHash: "hashed",
+    displayName: `User ${id}`,
+    locale: "de",
+    emailVerified: true,
+    roles: '["Member"]',
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd: pastInstant(),
+  });
+}
+
+async function seedMembership(userId: string, tenantId: string): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
+     VALUES ($1, $2, '["Member"]') ON CONFLICT (user_id, tenant_id) DO NOTHING`,
+    [tenantId, userId],
+  );
+}
+
+async function seedFileRef(id: string, tenantId: string, insertedById: string): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
+     VALUES ($1, $2, $3, $4, 'application/pdf', 1024, $5) ON CONFLICT (id) DO NOTHING`,
+    [id, tenantId, `storage/${id}`, `${id}.pdf`, insertedById],
+  );
+}
+
+// Setzt einen Tenant-Retention-Override über die GLEICHE API die der
+// Forget-Resolver liest — kein Test-Sonderpfad.
+async function seedFileRetentionOverride(
+  tenantId: string,
+  config: { keepFor: string; strategy: string; reference?: string },
+): Promise<void> {
+  const by = { ...TestUsers.systemAdmin, tenantId };
+  const result = await overrideExecutor.create(
+    { entityName: "fileRef", config: JSON.stringify(config), reason: "test", tenantId },
+    by,
+    createTenantDb(db, tenantId, "system"),
+  );
+  if (!result.isSuccess)
+    throw new Error(`seedFileRetentionOverride failed: ${JSON.stringify(result)}`);
+}
+
+async function fetchFileRow(
+  id: string,
+): Promise<{ id: string; inserted_by_id: string | null; is_deleted: boolean } | null> {
+  const result = await asRawClient(db).unsafe(
+    `SELECT id, inserted_by_id, is_deleted FROM file_refs WHERE id = $1`,
+    [id],
+  );
+  // biome-ignore lint/suspicious/noExplicitAny: drizzle execute typing
+  const rows = ((result as any).rows ?? result) as Array<{
+    id: string;
+    inserted_by_id: string | null;
+    is_deleted: boolean;
+  }>;
+  return rows[0] ?? null;
+}
+
+describe("file-retention :: Forget-Pipeline greift für fileRef", () => {
+  test("Default (keine Override-Policy) → Datei wird hart gelöscht (Art. 17)", async () => {
+    const userId = uuid(1);
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT_B);
+    await seedFileRef(uuid(101), TENANT_B, userId);
+
+    const result = await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    expect(result.processedUserIds).toContain(userId);
+    // Hard-Delete: Row weg.
+    expect(await fetchFileRow(uuid(101))).toBeNull();
+  });
+
+  test("Retention-Override fileRef→anonymize → Datei wird anonymisiert, Row bleibt", async () => {
+    const userId = uuid(2);
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT_A);
+    await seedFileRef(uuid(201), TENANT_A, userId);
+    await seedFileRetentionOverride(TENANT_A, { keepFor: "30d", strategy: "anonymize" });
+
+    const result = await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    expect(result.processedUserIds).toContain(userId);
+    const row = await fetchFileRow(uuid(201));
+    // Anonymize: Row existiert weiter, aber ohne Personenbezug (insertedById null).
+    expect(row).not.toBeNull();
+    expect(row?.inserted_by_id).toBeNull();
+    expect(row?.is_deleted).toBe(false);
+  });
+
+  test("Per-Tenant: derselbe User → anonymize in A, hard-delete in B", async () => {
+    const userId = uuid(3);
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT_A);
+    await seedMembership(userId, TENANT_B);
+    await seedFileRef(uuid(301), TENANT_A, userId);
+    await seedFileRef(uuid(302), TENANT_B, userId);
+    await seedFileRetentionOverride(TENANT_A, { keepFor: "30d", strategy: "anonymize" });
+    // TENANT_B: kein Override → Default-Delete.
+
+    await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    const aRow = await fetchFileRow(uuid(301));
+    expect(aRow).not.toBeNull();
+    expect(aRow?.inserted_by_id).toBeNull();
+
+    expect(await fetchFileRow(uuid(302))).toBeNull();
+  });
+});

package/src/user-data-rights/__tests__/run-forget-cleanup.integration.test.ts

@@ -22,6 +22,7 @@ import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
@@ -92,21 +93,9 @@ beforeAll(async () => {
       UNIQUE(user_id, tenant_id)
     )
   `);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS file_refs (
-      id UUID PRIMARY KEY,
-      tenant_id UUID NOT NULL,
-      storage_key TEXT NOT NULL,
-      file_name TEXT NOT NULL,
-      mime_type TEXT NOT NULL,
-      size INTEGER NOT NULL,
-      entity_type TEXT,
-      entity_id TEXT,
-      field_name TEXT,
-      inserted_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-      inserted_by_id TEXT
-    )
-  `);
+  // fileRef ist buildEntityTable-getrieben (softDelete) — echte Entity-Tabelle
+  // pushen statt hand-CREATE, damit is_deleted/deleted_at/deleted_by_id da sind.
+  await unsafePushTables(stack.db, { fileRefsTable });
 });
 
 afterAll(async () => {

package/src/user-data-rights/__tests__/run-user-export.integration.test.ts

@@ -21,6 +21,7 @@ import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
@@ -79,21 +80,9 @@ beforeAll(async () => {
       UNIQUE(user_id, tenant_id)
     )
   `);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS file_refs (
-      id UUID PRIMARY KEY,
-      tenant_id UUID NOT NULL,
-      storage_key TEXT NOT NULL,
-      file_name TEXT NOT NULL,
-      mime_type TEXT NOT NULL,
-      size INTEGER NOT NULL,
-      entity_type TEXT,
-      entity_id TEXT,
-      field_name TEXT,
-      inserted_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-      inserted_by_id TEXT
-    )
-  `);
+  // fileRef ist buildEntityTable-getrieben (softDelete) — echte Entity-Tabelle
+  // pushen statt hand-CREATE, damit is_deleted/deleted_at/deleted_by_id da sind.
+  await unsafePushTables(stack.db, { fileRefsTable });
 });
 
 afterAll(async () => {

package/src/user-data-rights-defaults/__tests__/user-data-rights-defaults.integration.test.ts

@@ -12,10 +12,12 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createDataRetentionFeature } from "../../data-retention";
@@ -53,24 +55,10 @@ beforeAll(async () => {
   // Drizzle-Generated-Queries kollidieren).
   await unsafeCreateEntityTable(stack.db, userEntity);
 
-  // file_refs ist framework-pgTable (nicht entity-getrieben, S1.5 hat
-  // die Schema-Sicht ohne buildEntityTable-Auto-Generation). Manuelle
-  // CREATE matched die Spalten aus framework/src/files/file-ref-table.ts
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS file_refs (
-      id UUID PRIMARY KEY,
-      tenant_id UUID NOT NULL,
-      storage_key TEXT NOT NULL,
-      file_name TEXT NOT NULL,
-      mime_type TEXT NOT NULL,
-      size INTEGER NOT NULL,
-      entity_type TEXT,
-      entity_id TEXT,
-      field_name TEXT,
-      inserted_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-      inserted_by_id TEXT
-    )
-  `);
+  // file_refs ist jetzt das buildEntityTable-getriebene fileRef-Entity
+  // (softDelete → is_deleted/deleted_at/deleted_by_id). Echte Entity-Tabelle
+  // pushen statt hand-CREATE, damit der is_deleted-Filter der Hooks greift.
+  await unsafePushTables(stack.db, { fileRefsTable });
 });
 
 afterAll(async () => {

package/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -30,9 +30,12 @@ import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 // Cleanup als TODO und faellen das in S2.U5 nochmal an.
 
 export const fileRefExportHook: UserDataExportHook = async (ctx) => {
+  // isDeleted:false — soft-deleted (trashed) Files gehören nicht ins
+  // Auskunfts-Bundle. Forget (delete-Hook unten) erfasst sie trotzdem.
   const rawRows = await selectMany(ctx.db, fileRefsTable, {
     tenantId: ctx.tenantId,
     insertedById: ctx.userId,
+    isDeleted: false,
   });
 
   // @cast-boundary db-row: drizzle liefert insertedAt als Instant

package/src/files/schema/file-ref.ts

@@ -1,58 +0,0 @@
-import {
-  createEntity,
-  createNumberField,
-  createTextField,
-  createTimestampField,
-} from "@cosmicdrift/kumiko-framework/engine";
-
-// fileRef — Schema-Sicht der File-Metadata-Tabelle aus dem Framework.
-//
-// Architektur-Entscheidung (Sprint 1.5):
-//
-// Die DB-Tabelle `file_refs` lebt weiterhin in
-// `framework/src/files/file-ref-table.ts` als drizzle pgTable, weil
-// die Hono-Upload-/Download-Routes (`createFileRoutes` in
-// `framework/src/api/server.ts`) sie direkt nutzen. Multipart-Upload
-// und Binary-Streaming passen nicht in das Write/Query-Handler-Pattern
-// — Routes bleiben framework-internal.
-//
-// Was hier passiert: dieselbe DB-Tabelle wird zusätzlich als
-// `r.entity("fileRef")` in einem bundled-feature deklariert. Das
-// ermoeglicht:
-//   1. r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
-//      in Sprint 2 — Forget-Flow + Daten-Export erkennen die Entity.
-//   2. r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
-//      in Sprint 5 — Tenant-Lifecycle löscht alle FileRefs.
-//   3. Boot-Validation für PII-Annotations greift (fileName, originalName).
-//
-// Kein buildEntityTable hier — die Mapping-Tabelle existiert schon im
-// Framework. Drizzle-Reads in den Sprint-2+-Hooks gehen direkt über
-// `fileRefsTable` aus `@cosmicdrift/kumiko-framework/files`.
-//
-// PII-Annotations (Sprint 0.1+0.7+1.7):
-//   - fileName  → pii: true (Originalname enthält oft Personen-Bezug:
-//                "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf")
-//
-//   Andere Felder brauchen KEINE Annotation:
-//   - storageKey, mimeType, size, entityType, entityId, fieldName,
-//     insertedById → keine PII-typischen Field-Namen, PII-Heuristik
-//     greift nicht (siehe boot-validator.ts PII_DIRECT_NAME_HINTS).
-//     Ein allowPlaintext-Marker wäre Über-Annotation ohne Effekt.
-//   - insertedAt → Audit-Timestamp, framework-managed.
-//
-// Tabellenname matched die Framework-pgTable damit r.entity-Reads über
-// dieselbe Postgres-Tabelle laufen.
-export const fileRefEntity = createEntity({
-  table: "file_refs",
-  fields: {
-    storageKey: createTextField({ required: true }),
-    fileName: createTextField({ required: true, pii: true }),
-    mimeType: createTextField({ required: true }),
-    size: createNumberField({ required: true }),
-    entityType: createTextField(),
-    entityId: createTextField(),
-    fieldName: createTextField(),
-    insertedAt: createTimestampField({ sortable: true, filterable: true }),
-    insertedById: createTextField(),
-  },
-});