@cosmicdrift/kumiko-framework 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/engine/boot-validator/screens-nav.ts

@@ -1,7 +1,7 @@
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
-import { normalizeEditField, normalizeListColumn } from "../types/screen";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
 //
@@ -62,6 +62,7 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) continue;
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -160,6 +161,7 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) continue;
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -341,6 +343,15 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          if (section.component.react === undefined && section.component.native === undefined) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) extension section ` +
+                `"${section.title}" has no component — declare a react/native component marker.`,
+            );
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/index.ts

@@ -226,7 +226,9 @@ export type {
   CustomScreenRoute,
   DateFieldDef,
   DeleteContext,
+  EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditLayout,
   EditSectionSpec,
   EntityDefinition,
@@ -325,7 +327,7 @@ export type {
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
 export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
-export { normalizeEditField, normalizeListColumn } from "./types/screen";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./types/screen";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/types/index.ts

@@ -204,7 +204,9 @@ export type {
   ConfigEditScreenDefinition,
   CustomScreenDefinition,
   CustomScreenRoute,
+  EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditLayout,
   EditSectionSpec,
   EntityEditScreenDefinition,
@@ -222,7 +224,7 @@ export type {
   ScreenSlots,
   ToolbarAction,
 } from "./screen";
-export { normalizeEditField, normalizeListColumn } from "./screen";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen";
 export type { TargetRef } from "./target-ref";
 export type {
   Subscribe,

package/src/engine/types/screen.ts

@@ -280,12 +280,31 @@ export type EditFieldSpec =
       readonly renderer?: FieldRenderer;
     };
 
-export type EditSectionSpec = {
+// A section is either a normal field-grid (default — `kind` omitted keeps
+// every existing screen-def working) or an extension slot that mounts a
+// feature-provided component. The extension component is resolved client-
+// side by name (same `__component` marker as custom screens / column
+// renderers) and receives the host entity name + id, so a bundled feature
+// (e.g. custom-fields) can load and persist its own data inside the form.
+export type EditSectionSpec = EditFieldsSection | EditExtensionSection;
+
+export type EditFieldsSection = {
+  readonly kind?: "fields";
   readonly title: string;
   readonly columns?: number;
   readonly fields: readonly EditFieldSpec[];
 };
 
+export type EditExtensionSection = {
+  readonly kind: "extension";
+  readonly title: string;
+  readonly component: PlatformComponent;
+};
+
+export function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection {
+  return section.kind === "extension";
+}
+
 export type EditLayout = {
   readonly sections: readonly EditSectionSpec[];
 };

package/src/files/__tests__/file-field-pipeline.integration.test.ts

@@ -37,6 +37,7 @@ import {
   unsafeCreateEntityTable,
 } from "../../stack";
 import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
+import { createFilesFeature } from "../feature";
 import { createLocalProvider } from "../local-provider";
 
 // Covers ALL four file-field variants: singular (file/image) stores a UUID in
@@ -73,7 +74,7 @@ beforeAll(async () => {
   patchFileInstanceofForBunTest();
   storagePath = await mkdtemp(join(tmpdir(), "kumiko-file-field-pipeline-"));
   stack = await setupTestStack({
-    features: [documentFeature],
+    features: [createFilesFeature(), documentFeature],
     files: { storageProvider: createLocalProvider(storagePath) },
   });
   await unsafeCreateEntityTable(stack.db, documentEntity);

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

@@ -28,7 +28,7 @@ import {
   patchFileInstanceofForBunTest,
 } from "../../testing";
 import { fileRefsTable } from "../file-ref-table";
-import { FILE_UPLOADED_EVENT_TYPE, type FileRoutesOptions } from "../file-routes";
+import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider } from "../types";
@@ -248,18 +248,17 @@ describe("file upload flow via API", () => {
     expect(downloaded[0]).toBe(0x89); // PNG magic byte
   });
 
-  test("upload appends files:event:uploaded to the fileRef stream", async () => {
-    // Load the full event stream for the just-uploaded FileRef. Phase 1
-    // guarantees exactly one event per upload — "uploaded" at version 1.
+  test("upload emits fileRef.created to the entity stream", async () => {
+    // fileRef is a standard ES entity — the upload goes through the entity
+    // executor, so the stream carries exactly one `fileRef.created` at v1.
     const events = await loadAggregate(testDb.db, uploadedFileId, adminUser.tenantId);
 
     expect(events).toHaveLength(1);
     const event = events[0];
-    expect(event?.type).toBe(FILE_UPLOADED_EVENT_TYPE);
+    expect(event?.type).toBe("fileRef.created");
     expect(event?.version).toBe(1);
 
-    type UploadedPayload = {
-      fileRefId: string;
+    type CreatedPayload = {
       fileName: string;
       mimeType: string;
       size: number;
@@ -269,8 +268,10 @@ describe("file upload flow via API", () => {
       data?: unknown;
       binary?: unknown;
     };
-    const payload = event!.payload as UploadedPayload;
-    expect(payload.fileRefId).toBe(uploadedFileId);
+    // The entity executor strips `id` from the event payload (it's the
+    // aggregateId / stream id, which we loaded by above) and threads
+    // insertedById through metadata — neither appears in payload.
+    const payload = event!.payload as CreatedPayload;
     expect(payload.fileName).toBe("logo.png");
     expect(payload.mimeType).toBe("image/png");
     expect(payload.size).toBe(testPngContent.length);

package/src/files/__tests__/storage-tracking.integration.test.ts

@@ -14,6 +14,7 @@ import type { SessionUser } from "../../engine";
 import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
 import {
+  createFilesFeature,
   createInMemoryFileProvider,
   filesStorageTrackingFeature,
   type InMemoryFileProvider,
@@ -40,7 +41,7 @@ beforeAll(async () => {
   patchFileInstanceofForBunTest();
   provider = createInMemoryFileProvider();
   stack = await setupTestStack({
-    features: [filesStorageTrackingFeature],
+    features: [createFilesFeature(), filesStorageTrackingFeature],
     files: { storageProvider: provider },
   });
 });

package/src/files/feature.ts

@@ -0,0 +1,21 @@
+import { defineFeature, type FeatureDefinition } from "../engine";
+import { fileRefEntity } from "./file-ref-entity";
+
+export { fileRefEntity } from "./file-ref-entity";
+
+// files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
+// den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
+// `fileRef.created`/`fileRef.deleted` → applyEntityEvent materialisiert
+// `file_refs`). Soft-Delete/Anonymize/Restore/Retention kommen damit
+// generisch aus dem Entity-Lifecycle + data-retention — keine
+// file-spezifische Lösch-Logik.
+//
+// `r.entity` macht die Tabelle für PII-Boot-Validation +
+// userData/tenantData-Extensions sichtbar und registriert die implizite
+// Entity-Projektion (für rebuildProjection). Liegt im Framework neben
+// file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
+export function createFilesFeature(): FeatureDefinition {
+  return defineFeature("files", (r) => {
+    r.entity("fileRef", fileRefEntity);
+  });
+}

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

@@ -0,0 +1,30 @@
+import { createEntity, createNumberField, createTextField, createTimestampField } from "../engine";
+
+// fileRef — das File-Metadata-Entity. Ganz normales ES-Entity: Upload/Delete
+// laufen über den Standard-Executor (file-routes.ts), die Tabelle `file_refs`
+// wird via buildEntityTable aus dieser Definition gebaut.
+//
+// softDelete: true — wie das `user`-Entity + die data-retention-Strategien.
+// Ein Delete markiert `isDeleted=true` (wiederherstellbar, kein "sofort weg");
+// echtes Erasure (Art. 17) läuft über den Forget-Hook + Retention-Cleanup.
+//
+// PII-Annotations:
+//   - fileName → pii: true (Originalname enthält oft Personen-Bezug:
+//     "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). Andere Felder
+//     (storageKey, mimeType, size, entityType, entityId, fieldName,
+//     insertedById, insertedAt) treffen die PII-Heuristik nicht.
+export const fileRefEntity = createEntity({
+  table: "file_refs",
+  softDelete: true,
+  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(),
+  },
+});

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

@@ -1,22 +1,13 @@
-// sql now comes from native dialect
-import { instant, integer, table as pgTable, sql, text, uuid } from "../db/dialect";
+import { buildEntityTable } from "../db/table-builder";
+import { fileRefEntity } from "./file-ref-entity";
 
-// `id` is a UUID (not serial): it doubles as the aggregate-id for the
-// `fileRef` event stream — every upload appends exactly one
-// `files:event:uploaded` event keyed by this id. UUIDs also close the
-// enumeration-attack vector on /files/:id URLs.
-export const fileRefsTable = pgTable("file_refs", {
-  id: uuid("id").primaryKey(),
-  tenantId: uuid("tenant_id").notNull(),
-  storageKey: text("storage_key").notNull(),
-  fileName: text("file_name").notNull(),
-  mimeType: text("mime_type").notNull(),
-  size: integer("size").notNull(),
-  entityType: text("entity_type"),
-  // entityId references any entity (mostly UUID-keyed under ES). Text keeps
-  // the column backward-compat with older integer-keyed entities too.
-  entityId: text("entity_id"),
-  fieldName: text("field_name"),
-  insertedAt: instant("inserted_at").default(sql`now()`).notNull(),
-  insertedById: text("inserted_by_id"),
-});
+// `file_refs` ist die read-table des `fileRef`-Entity. Aus der Entity-
+// Definition gebaut (kein hand-gepflegtes pgTable mehr), damit die implizite
+// Entity-Projektion (Rebuild) und der Live-Executor-Write spaltengleich auf
+// dieselbe Tabelle schreiben — Single Source, keine Dual-Definition-Drift.
+//
+// `id` ist UUID und doppelt als Aggregate-Id des fileRef-Event-Streams:
+// jeder Upload appended `fileRef.created`, jeder Delete `fileRef.deleted`
+// (Standard-Entity-Auto-Verben). UUIDs schließen die Enumeration-Attacke
+// auf /files/:id.
+export const fileRefsTable = buildEntityTable("fileRef", fileRefEntity);

package/src/files/file-routes.ts

@@ -1,13 +1,13 @@
-import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { Hono } from "hono";
-import { z } from "zod";
 import { getUser } from "../api/auth-middleware";
-import type { DbConnection, DbTx } from "../db/connection";
-import type { EventDef } from "../engine/types";
+import type { DbConnection } from "../db/connection";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { createTenantDb } from "../db/tenant-db";
 import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
-import { append as appendEvent } from "../event-store/event-store";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
+import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileStorageProvider } from "./types";
 import { buildStorageKey, validateFile } from "./types";
@@ -29,38 +29,11 @@ export type FileRef = {
   insertedById: string | null;
 };
 
-// Event emitted after a successful upload. Downstream hooks / MSPs subscribe
-// on `fileUploadedEvent.name` via an r.multiStreamProjection apply map. The
-// payload carries metadata + the storage key — never the binary itself.
-// Consumers that need the bytes call `ctx.files.ref(payload.storageKey).read()`.
-//
-// Packaged as a framework-owned EventDef so consumers can narrow the raw
-// StoredEvent.payload via `typedPayload(event, fileUploadedEvent)` instead
-// of hand-casting. Schema version starts at 1; bump in lockstep with an
-// r.eventMigration when the shape breaks.
-export const fileUploadedPayloadSchema = z.object({
-  fileRefId: z.uuid(),
-  storageKey: z.string().min(1),
-  fileName: z.string().min(1),
-  mimeType: z.string().min(1),
-  size: z.number().int().nonnegative(),
-  entityType: z.string().nullable(),
-  entityId: z.string().nullable(),
-  fieldName: z.string().nullable(),
-  insertedById: z.string().min(1),
-});
-
-export type FileUploadedPayload = z.infer<typeof fileUploadedPayloadSchema>;
-
-export const fileUploadedEvent: EventDef<FileUploadedPayload> = {
-  name: "files:event:uploaded",
-  schema: fileUploadedPayloadSchema,
-  version: 1,
-};
-
-// Convenience re-export so apps that only reach for the event name (e.g. as
-// an apply-map key) don't have to dereference `.name` everywhere.
-export const FILE_UPLOADED_EVENT_TYPE = fileUploadedEvent.name;
+// fileRef is a standard ES entity: upload/delete go through the entity
+// executor (executor.create/delete below), which emits `fileRef.created` /
+// `fileRef.deleted` and materialises file_refs via applyEntityEvent in one
+// tx. Downstream MSPs (e.g. storage-tracking) subscribe on those entity
+// event types — there is no bespoke files:event:* anymore.
 
 // Checks whether `user` may read/delete the given file. The default guard
 // (ownerOrPrivilegedGuard) approves uploaders + any role in privilegedRoles.
@@ -110,6 +83,13 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   const { db, storageProvider } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
   const guard: FileAccessGuard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
+  // Standard entity executor for fileRef — self-contained (table + entity),
+  // no registry needed. create/delete emit fileRef.created/deleted and write
+  // file_refs via applyEntityEvent in one tx (read-your-own-write), exactly
+  // like any other entity's lifecycle.
+  const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+    entityName: "fileRef",
+  });
   const api = new Hono();
 
   // POST /files — multipart upload.
@@ -169,26 +149,16 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const data = new Uint8Array(await file.arrayBuffer());
     await storageProvider.write(storageKey, data, file.type);
 
-    // Atomic: insert FileRef + append files:event:uploaded in one tx. Either
-    // both land or neither — no dangling FileRef without event, no event
-    // referencing a row that doesn't exist.
-    await db.begin(async (tx: DbTx) => {
-      const { insertOne } = await import("../bun-db/query");
-      await insertOne(tx, fileRefsTable, {
+    // Create via the standard entity executor: emits fileRef.created +
+    // materialises the file_refs row in one tx (read-your-own-write). id is
+    // explicit so the response + storageKey stay consistent; tenantId,
+    // insertedAt and insertedById are set by applyEntityEvent from the event
+    // metadata. The binary was written above, outside the tx — a create
+    // failure orphans bytes (cleanup-job sweeps) rather than committing a row
+    // whose binary is missing.
+    const result = await executor.create(
+      {
         id: fileRefId,
-        tenantId: user.tenantId,
-        storageKey,
-        fileName: file.name,
-        mimeType: file.type,
-        size: file.size,
-        entityType: entityType ?? null,
-        entityId: entityId ?? null,
-        fieldName: fieldName ?? null,
-        insertedById: user.id,
-      });
-
-      const payload: FileUploadedPayload = {
-        fileRefId,
         storageKey,
         fileName: file.name,
         mimeType: file.type,
@@ -196,21 +166,13 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
         entityType: entityType ?? null,
         entityId: entityId ?? null,
         fieldName: fieldName ?? null,
-        insertedById: user.id,
-      };
-      await appendEvent(tx, {
-        aggregateId: fileRefId,
-        aggregateType: "fileRef",
-        tenantId: user.tenantId,
-        expectedVersion: 0,
-        type: fileUploadedEvent.name,
-        // EventToAppend wants a Record — payload is typed through the
-        // EventDef so the cast collapses to a single boundary, not a
-        // double-`as unknown as` at the call site.
-        payload: payload as Record<string, unknown>, // @cast-boundary engine-payload
-        metadata: { userId: user.id },
-      });
-    });
+      },
+      user,
+      createTenantDb(db, user.tenantId),
+    );
+    if (!result.isSuccess) {
+      return c.json({ error: "upload_failed" }, 500);
+    }
 
     return c.json(
       {
@@ -265,15 +227,17 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const decision = await guard({ fileRef, user, operation: "delete" });
     if (decision === "deny") return c.json({ error: "not_found" }, 404);
 
-    // Tombstone-Reihenfolge: DB-Row löschen FIRST, Bytes danach. Wenn der
-    // Storage-Call hängt oder fehlschlägt, sieht der User trotzdem den
-    // konsistenten "weg"-Zustand (kein Read findet die Row mehr) und der
-    // Cleanup-Job sweept die orphan'd bytes wie beim fehlgeschlagenen
-    // Upload. Umgekehrt liesse ein storage-success + db-fail eine Row mit
-    // permanent-broken Reference zurück — aus Sicht der API "Datei
-    // existiert" aber jeder Read 404t aus dem Provider.
-    await deleteMany(db, fileRefsTable, { id: id });
-    await storageProvider.delete(fileRef.storageKey);
+    // Delete via the standard entity executor: emits fileRef.deleted and
+    // applies it in one tx. fileRef is softDelete → the row is flagged
+    // isDeleted=true (reads filter it out) and stays recoverable; the binary
+    // is intentionally KEPT so a restore can bring the file back. Hard
+    // erasure of row + binary is the job of the forget-flow (Art. 17) and the
+    // generic data-retention cleanup — same lifecycle as any soft-delete
+    // entity, not a files-specific path.
+    const result = await executor.delete({ id }, user, createTenantDb(db, user.tenantId));
+    if (!result.isSuccess) {
+      return c.json({ error: "not_found" }, 404);
+    }
     return c.json({ ok: true });
   });
 
@@ -343,7 +307,9 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   });
 
   async function loadFileForTenant(id: string, tenantId: TenantId): Promise<FileRef | null> {
-    const [row] = await selectMany(db, fileRefsTable, { id, tenantId });
+    // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
+    // never surface to reads/guards.
+    const [row] = await selectMany(db, fileRefsTable, { id, tenantId, isDeleted: false });
     return (row as FileRef | undefined) ?? null; // @cast-boundary db-row
   }
 

package/src/files/index.ts

@@ -1,21 +1,17 @@
+export { createFilesFeature } from "./feature";
 export type { FileContext, FileHandle } from "./file-handle";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, deriveKey } from "./file-handle";
+export { fileRefEntity } from "./file-ref-entity";
 export { fileRefsTable } from "./file-ref-table";
 export type {
   FileAccessDecision,
   FileAccessGuard,
   FileRef,
   FileRoutesOptions,
-  FileUploadedPayload,
-} from "./file-routes";
-export {
-  createFileRoutes,
-  FILE_UPLOADED_EVENT_TYPE,
-  fileUploadedEvent,
-  fileUploadedPayloadSchema,
 } from "./file-routes";
+export { createFileRoutes } from "./file-routes";
 export type { InMemoryFileProvider } from "./in-memory-provider";
 export { createInMemoryFileProvider } from "./in-memory-provider";
 export { createLocalProvider } from "./local-provider";

package/src/files/storage-tracking.ts

@@ -10,10 +10,21 @@
 // consumer-cursor row. Apps that want it pass filesStorageTrackingFeature
 // into createApp / setupTestStack alongside their domain features.
 
+import { entityEventName } from "../db";
 import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect";
 import { incrementCounter } from "../db/query";
-import { defineFeature, typedPayload } from "../engine";
-import { fileUploadedEvent } from "./file-routes";
+import { defineFeature } from "../engine";
+
+// fileRef is a standard ES entity, so usage tracking subscribes to its
+// auto-verb events. `fileRef.created` payload carries the entity fields
+// (incl. size); `fileRef.deleted` carries `{ previous }` (the pre-delete
+// row), so the byte count to reverse lives at previous.size.
+const FILE_REF_CREATED = entityEventName("fileRef", "created");
+const FILE_REF_DELETED = entityEventName("fileRef", "deleted");
+
+function readNumber(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}
 
 // bigint in `mode: "number"` returns a JS number (safe up to 2^53 ≈ 9e15
 // bytes ≈ 8 petabytes per tenant — large enough for any practical storage
@@ -32,8 +43,8 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
     name: "tenant-storage-usage",
     table: tenantStorageUsageTable,
     apply: {
-      [fileUploadedEvent.name]: async (event, tx) => {
-        const payload = typedPayload(event, fileUploadedEvent);
+      [FILE_REF_CREATED]: async (event, tx) => {
+        const size = readNumber(event.payload["size"]);
 
         // UPSERT: INSERT on first upload per tenant, otherwise atomic increment.
         // The SQL increment guarantees correctness under concurrent dispatcher
@@ -42,8 +53,27 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
         await incrementCounter(
           tx,
           tenantStorageUsageTable,
-          { tenantId: event.tenantId, totalBytes: payload.size, fileCount: 1 },
-          { totalBytes: payload.size, fileCount: 1 },
+          { tenantId: event.tenantId, totalBytes: size, fileCount: 1 },
+          { totalBytes: size, fileCount: 1 },
+          { set: { lastUpdatedAt: sql`now()` } },
+        );
+      },
+      [FILE_REF_DELETED]: async (event, tx) => {
+        // Delete events carry the pre-delete row under `previous`.
+        const previous = event.payload["previous"];
+        const size =
+          previous && typeof previous === "object" && !Array.isArray(previous)
+            ? readNumber((previous as Record<string, unknown>)["size"]) // @cast-boundary engine-payload
+            : 0;
+        // Decrement on delete. INSERT values are 0/0 so a delete that somehow
+        // precedes any upload can't create negative usage; the on-conflict
+        // path applies the real negative delta. Async (dispatcher) —
+        // eventually-consistent with the write-tx that emitted fileRef.deleted.
+        await incrementCounter(
+          tx,
+          tenantStorageUsageTable,
+          { tenantId: event.tenantId, totalBytes: 0, fileCount: 0 },
+          { totalBytes: -size, fileCount: -1 },
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },

package/src/testing/e2e-generator.ts

@@ -30,6 +30,7 @@ import {
   type EntityEditScreenDefinition,
   type EntityListScreenDefinition,
   type FieldDefinition,
+  isExtensionEditSection,
   normalizeEditField,
   normalizeListColumn,
   parseQn,
@@ -234,6 +235,7 @@ function collectRequiredEditFields(
 ): string[] {
   const out: string[] = [];
   for (const section of screen.layout.sections) {
+    if (isExtensionEditSection(section)) continue;
     for (const rawField of section.fields) {
       const { field } = normalizeEditField(rawField);
       const def = entity.fields[field];
@@ -271,6 +273,7 @@ function buildEditFillOps(
   // form; Felder ohne Fixture-Wert (file/image/…) werden übersprungen.
   const ops: EditFillOp[] = [];
   for (const section of screen.layout.sections) {
+    if (isExtensionEditSection(section)) continue;
     for (const raw of section.fields) {
       const { field } = normalizeEditField(raw);
       const def = entity.fields[field];
@@ -317,6 +320,7 @@ function pickIdentifyingForEdit(
     : undefined;
 
   for (const section of editScreen.layout.sections) {
+    if (isExtensionEditSection(section)) continue;
     for (const rawField of section.fields) {
       const { field } = normalizeEditField(rawField);
       if (entity.fields[field]?.type !== "text") continue;

package/src/ui-types/index.ts

@@ -46,7 +46,9 @@ export type {
   ConfigEditScreenDefinition,
   CustomScreenDefinition,
   CustomScreenRoute,
+  EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditLayout,
   EditSectionSpec,
   EntityEditScreenDefinition,
@@ -64,6 +66,10 @@ export type {
   ScreenSlots,
   ToolbarAction,
 } from "../engine/types/screen";
-export { normalizeEditField, normalizeListColumn } from "../engine/types/screen";
+export {
+  isExtensionEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../engine/types/screen";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
 export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";