@cosmicdrift/kumiko-framework 0.312.0 → 0.314.0

package/src/db/bun-provider.ts

@@ -8,7 +8,11 @@
 // Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
@@ -25,13 +29,14 @@ export function createBunConnection(url: string, options: DbConnectionOptions =
     pgOpts.connect_timeout = options.connectTimeoutSeconds;
   const listenClient = postgres(url, pgOpts);
 
+  const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
   return {
     db,
     client: listenClient,
     listenClient,
     close: async () => {
-      await db.end();
-      await listenClient.end();
+      await db.end({ timeout: closeTimeout });
+      await listenClient.end({ timeout: closeTimeout });
     },
   };
 }

package/src/db/connection.ts

@@ -3,6 +3,7 @@
 import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "./api";
 
 // Raw client types (postgres-js | Bun.SQL) — the name used across query/
 // event-store/pipeline call sites. The structural pool handle from ./api is
@@ -33,9 +34,8 @@ export function createDbConnection(
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }
 

package/src/db/eagerload.ts

@@ -26,6 +26,7 @@
 import { requestContext } from "../api/request-context";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto";
 import { selectMany } from "../db/query";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target";
 import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
 import {
   collectEncryptedFieldNames,
@@ -67,21 +68,13 @@ function isReferenceField(field: FieldDefinition): field is ReferenceFieldDef {
   return field.type === "reference";
 }
 
-function parseRefEntity(raw: string): string {
-  // Same-feature ("user") oder cross-feature ("users:user") — wir
-  // brauchen nur den entity-name (Names sind global eindeutig in
-  // entityMap). Der feature-prefix dient nur der Author-Klarheit.
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 export function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[] {
   const out: ReferenceFieldEntry[] = [];
   for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
     if (!isReferenceField(fieldDef)) continue;
     out.push({
       fieldName,
-      refEntityName: parseRefEntity(fieldDef.entity),
+      refEntityName: parseRefTargetEntityName(fieldDef.entity),
       multiple: fieldDef.multiple === true,
     });
   }

package/src/db/index.ts

@@ -114,7 +114,7 @@ export {
   type PgErrorInfo,
 } from "./pg-error";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock";
-export { executeRawQuery } from "./queries/raw-sql";
+export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api";
 export {
   asRawClient,

package/src/db/postgres-provider.ts

@@ -3,7 +3,11 @@
 // `asRawClient(db)` wrappt .unsafe und .begin transparent.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const pgOptions: Parameters<typeof postgres>[1] = {};
@@ -18,8 +22,7 @@ export function createPgConnection(url: string, options: DbConnectionOptions = {
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }

package/src/db/queries/event-consumer.ts

@@ -326,11 +326,12 @@ export async function selectConsumerForUpdate(
   db: AnyDb,
   name: string,
   instanceId: string,
-): Promise<void> {
-  await asRawClient(db).unsafe(
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
     `SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`,
     [name, instanceId],
-  );
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
 }
 
 export async function updateConsumerRebuildCursor(

package/src/engine/boot-validator/__tests__/transfer-graph.test.ts

@@ -115,6 +115,18 @@ describe("validateTransferGraph", () => {
     expect(() => validate(chain)).not.toThrow();
   });
 
+  // A feature-prefixed reference target ("<feature>:<entity>") must resolve
+  // to the same entity name as an unprefixed one, or a chain built entirely
+  // out of prefixed refs would silently never trip the depth limit.
+  test("counts a chain of feature-prefixed reference targets into the depth limit", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= MAX_TRANSFER_DEPTH + 1; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `graph:e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).toThrow(/deeper than the 5-level limit.*e0 -> e1/s);
+  });
+
   test("terminates on a reference cycle instead of reporting false depth", () => {
     expect(() =>
       validate({

package/src/engine/boot-validator/transfer-graph.ts

@@ -1,3 +1,4 @@
+import { parseRefTargetEntityName } from "../parse-ref-target";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 
 // --- Transfer-graph boot validation (fw#3088) ---
@@ -39,7 +40,7 @@ function referenceTargets(entity: EntityDefinition): readonly string[] {
   for (const field of Object.values(entity.fields)) {
     if (field.type !== "reference") continue;
     if (field.multiple === true) continue;
-    targets.push(field.entity);
+    targets.push(parseRefTargetEntityName(field.entity));
   }
   return targets;
 }

package/src/engine/index.ts

@@ -264,6 +264,8 @@ export {
   userCanReadFieldRow,
   userCanWriteFieldRow,
 } from "./ownership";
+export type { ParsedRefTarget } from "./parse-ref-target";
+export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
@@ -431,6 +433,7 @@ export type {
   JobDefinition,
   JobHandlerFn,
   JobTrigger,
+  JobTriggerEvent,
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,

package/src/engine/parse-ref-target.ts

@@ -20,3 +20,9 @@ export function parseRefTarget(raw: string, currentFeature: string): ParsedRefTa
   }
   return { featureName: raw.slice(0, idx), entityName: raw.slice(idx + 1) };
 }
+
+// Entity names are globally unique in the registry, so callers that only
+// need the entity (not its owning feature) can drop the currentFeature arg.
+export function parseRefTargetEntityName(raw: string): string {
+  return parseRefTarget(raw, "").entityName;
+}

package/src/engine/registry-validate.ts

@@ -2,6 +2,7 @@ import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
+import { parseRefTargetEntityName } from "./parse-ref-target";
 import type {
   RegistryState,
   SearchableReferenceField,
@@ -192,16 +193,6 @@ export function applyExtensionUsages(state: RegistryState): void {
   }
 }
 
-// "customer" (same-feature) or "users:customer" (cross-feature,
-// "<featureName>:<entityName>") — only the entity name matters here, names
-// are globally unique in entityMap. Local duplicate of the same parse done
-// in db/eagerload.ts's parseRefEntity — this loop has no feature context to
-// hand to engine/parse-ref-target.ts's parseRefTarget.
-function parseReferenceTargetEntityName(raw: string): string {
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 // fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
 // searchable reference ILIKEs the label column — an implicit or explicit
 // "id" default would 500 on every search request. Fail at boot.
@@ -224,7 +215,7 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
-  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntityName = parseRefTargetEntityName(field.entity);
   const targetEntity = entityMap.get(targetEntityName);
   if (targetEntity !== undefined) {
     if (
@@ -273,7 +264,7 @@ function buildSortableReferenceField(
   }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName: parseRefTargetEntityName(field.entity),
     labelField: field.labelField,
   };
 }

package/src/engine/types/index.ts

@@ -185,6 +185,7 @@ export type {
   HandlerRef,
   JobContext,
   JobRunnerRef,
+  JobTriggerEvent,
   MemberReader,
   NameOrRef,
   NotifyFactory,

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

@@ -8,6 +8,7 @@ import { buildServer } from "../../api/server";
 import { configurePiiSubjectKms, InMemoryKmsAdapter } from "../../crypto";
 import {
   createEntity,
+  createFileField,
   createImageField,
   createRegistry,
   createTextField,
@@ -35,7 +36,13 @@ import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider, SignedUrlOptions } from "../types";
-import { parseMaxSize, sniffMimeType, validateFile, validateFileContent } from "../types";
+import {
+  parseMaxSize,
+  resolveUploadMimeType,
+  sniffMimeType,
+  validateFile,
+  validateFileContent,
+} from "../types";
 
 // UUID for "this row doesn't exist" assertions. Valid v4 format so PG accepts
 // the query — the row just isn't there. Pre-v1 files-feature tests used
@@ -59,6 +66,7 @@ const testTenantEntity = createEntity({
   fields: {
     name: createTextField({ personal: false, reason: "test_fixture", required: true }),
     logo: createImageField({ maxSize: "2mb", accept: ["png", "jpg"] }),
+    importFile: createFileField({ maxSize: "2mb", accept: ["csv"] }),
   },
 });
 
@@ -296,6 +304,91 @@ describe("file validation", () => {
       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
     );
   });
+
+  // --- .csv declared as application/vnd.ms-excel (Windows browsers) ---
+
+  test("validateFile accepts .csv declared as application/vnd.ms-excel when csv is in accept", () => {
+    expect(
+      validateFile(
+        { fileName: "data.csv", mimeType: "application/vnd.ms-excel", size: 100 },
+        { accept: ["csv"] },
+      ),
+    ).toBeNull();
+  });
+
+  test("validateFile does not extend the vnd.ms-excel alias to extensions other than csv", () => {
+    const error = validateFile(
+      { fileName: "photo.jpg", mimeType: "application/vnd.ms-excel", size: 100 },
+      { accept: ["jpg"] },
+    );
+    expectErrorIncludes(error, "mime_mismatch");
+  });
+
+  test("validateFile rejects a prototype-property mimeType instead of treating it as an alias match", () => {
+    const error = validateFile(
+      { fileName: "photo.jpg", mimeType: "constructor", size: 100 },
+      { accept: ["jpg"] },
+    );
+    expectErrorIncludes(error, "mime_mismatch");
+  });
+
+  describe("resolveUploadMimeType", () => {
+    const textCsvBytes = new TextEncoder().encode("name,age\nAda,36\n");
+
+    test("rewrites .csv + application/vnd.ms-excel to text/csv when bytes are text", () => {
+      expect(resolveUploadMimeType("data.csv", "application/vnd.ms-excel", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "text/csv",
+      });
+    });
+
+    test("rewrites regardless of charset suffix or case", () => {
+      expect(
+        resolveUploadMimeType("data.csv", "Application/VND.MS-EXCEL; charset=utf-8", textCsvBytes),
+      ).toEqual({ kind: "ok", mimeType: "text/csv" });
+    });
+
+    test("rejects .csv + application/vnd.ms-excel when bytes are a real OLE binary", () => {
+      const result = resolveUploadMimeType("data.csv", "application/vnd.ms-excel", docBytes);
+      expect(result.kind).toBe("rejected");
+      if (result.kind === "rejected") {
+        expectErrorIncludes(result.error, "content_mismatch");
+      }
+    });
+
+    test("rejects .csv + application/vnd.ms-excel when bytes are a ZIP container (.xlsx)", () => {
+      const result = resolveUploadMimeType("data.csv", "application/vnd.ms-excel", docxBytes);
+      expect(result.kind).toBe("rejected");
+      if (result.kind === "rejected") {
+        expectErrorIncludes(result.error, "content_mismatch");
+      }
+    });
+
+    test("leaves .csv + text/plain unchanged", () => {
+      expect(resolveUploadMimeType("data.csv", "text/plain", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "text/plain",
+      });
+    });
+
+    test("leaves .xls + application/vnd.ms-excel unchanged (alias is csv-only)", () => {
+      expect(resolveUploadMimeType("data.xls", "application/vnd.ms-excel", docBytes)).toEqual({
+        kind: "ok",
+        mimeType: "application/vnd.ms-excel",
+      });
+    });
+
+    test("a prototype-property extension or mimeType never resolves as an alias", () => {
+      expect(resolveUploadMimeType("x.constructor", "name", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "name",
+      });
+      expect(resolveUploadMimeType("data.csv", "constructor", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "constructor",
+      });
+    });
+  });
 });
 
 // --- Integration: Upload → Download → Delete via real HTTP API ---
@@ -523,6 +616,40 @@ describe("doc/docx upload is content-verified against magic bytes", () => {
   });
 });
 
+// Bun's formData() derives File#type from the filename, so .csv never
+// arrives as vnd.ms-excel here; the csv alias is covered by the unit tests above.
+describe("vnd.ms-excel via HTTP (.xls)", () => {
+  const docBytes = new Uint8Array([
+    0xd0,
+    0xcf,
+    0x11,
+    0xe0,
+    0xa1,
+    0xb1,
+    0x1a,
+    0xe1,
+    ...Array(20).fill(0),
+  ]);
+
+  test("unattached .xls declared as application/vnd.ms-excel keeps its declared mimeType unchanged", async () => {
+    const res = await uploadFile(adminUser, "legacy.xls", docBytes, "application/vnd.ms-excel");
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.mimeType).toBe("application/vnd.ms-excel");
+  });
+
+  test("attached .xls upload is rejected by the importFile field's csv-only accept list", async () => {
+    const res = await uploadFile(adminUser, "legacy.xls", docBytes, "application/vnd.ms-excel", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "importFile",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid_file_type");
+  });
+});
+
 // --- Cross-user access within a tenant (attached file owner-scope) ---
 
 describe("attached file owner-scope", () => {

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

@@ -0,0 +1,46 @@
+// fileRefStorageDelta — the single source of truth the tenant-storage-usage
+// MSP's apply handlers and transferTenantStorageUsage's replay both use to
+// turn one fileRef event into a signed (bytes, files) delta.
+
+import { describe, expect, test } from "bun:test";
+import { entityEventName } from "../../db";
+import { fileRefStorageDelta } from "../storage-tracking";
+
+const CREATED = entityEventName("fileRef", "created");
+const DELETED = entityEventName("fileRef", "deleted");
+const RESTORED = entityEventName("fileRef", "restored");
+
+describe("fileRefStorageDelta", () => {
+  test("created: positive delta from payload.size", () => {
+    expect(fileRefStorageDelta({ type: CREATED, payload: { size: 42 } })).toEqual({
+      bytes: 42,
+      files: 1,
+    });
+  });
+
+  test("created: missing/non-numeric size reads as 0 bytes, still counts a file", () => {
+    expect(fileRefStorageDelta({ type: CREATED, payload: {} })).toEqual({ bytes: 0, files: 1 });
+  });
+
+  test("deleted: negative delta from payload.previous.size", () => {
+    expect(fileRefStorageDelta({ type: DELETED, payload: { previous: { size: 42 } } })).toEqual({
+      bytes: -42,
+      files: -1,
+    });
+  });
+
+  test("deleted: missing previous reads as 0 bytes, still counts -1 file", () => {
+    expect(fileRefStorageDelta({ type: DELETED, payload: {} })).toEqual({ bytes: 0, files: -1 });
+  });
+
+  test("restored: positive delta from payload.previous.size, symmetric to delete", () => {
+    expect(fileRefStorageDelta({ type: RESTORED, payload: { previous: { size: 42 } } })).toEqual({
+      bytes: 42,
+      files: 1,
+    });
+  });
+
+  test("an unrelated event type returns null", () => {
+    expect(fileRefStorageDelta({ type: "fileRef.renamed", payload: { size: 42 } })).toBeNull();
+  });
+});

package/src/files/file-routes.ts

@@ -30,6 +30,7 @@ import type { FileProviderResolver } from "./provider-resolver";
 import {
   buildStorageKey,
   resolveServedContentType,
+  resolveUploadMimeType,
   validateFile,
   validateFileContent,
 } from "./types";
@@ -240,13 +241,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       return c.json({ error: contentValidationError }, 400);
     }
 
+    const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
+    if (mimeTypeResolution.kind === "rejected") {
+      return c.json({ error: mimeTypeResolution.error }, 400);
+    }
+    const mimeType = mimeTypeResolution.mimeType;
+
     // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
     // inside a PG connection's tx window). On DB-tx rollback below the bytes
     // are orphaned in the provider; cleanup-jobs sweep those later. Losing a
     // row on append-failure is acceptable; corrupting a committed row with a
     // missing binary is not.
     const storageProvider = await options.resolveProvider(user.tenantId);
-    await storageProvider.write(storageKey, data, file.type);
+    await storageProvider.write(storageKey, data, mimeType);
 
     // Create via the standard entity executor: emits fileRef.created +
     // materialises the file_refs row in one tx (read-your-own-write). id is
@@ -260,7 +267,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
         id: fileRefId,
         storageKey,
         fileName: file.name,
-        mimeType: file.type,
+        mimeType,
         size: file.size,
         entityType: entityType ?? null,
         entityId: entityId ?? null,
@@ -277,7 +284,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       {
         id: fileRefId,
         fileName: file.name,
-        mimeType: file.type,
+        mimeType,
         size: file.size,
         storageKey,
       },

package/src/files/index.ts

@@ -26,12 +26,18 @@ export {
   isFileProviderPlugin,
   makeFileProviderResolver,
 } from "./provider-resolver";
-export { filesStorageTrackingFeature, tenantStorageUsageTable } from "./storage-tracking";
+export {
+  fileRefStorageDelta,
+  filesStorageTrackingFeature,
+  tenantStorageUsageTable,
+  transferTenantStorageUsage,
+} from "./storage-tracking";
 export type {
   FileMetadata,
   FileStorageProvider,
   FileValidationOptions,
   SignedUrlOptions,
+  UploadMimeTypeResolution,
   WriteStreamOptions,
 } from "./types";
 export {
@@ -39,6 +45,8 @@ export {
   buildStorageKey,
   normalizeMimeType,
   parseMaxSize,
+  resolveUploadMimeType,
+  sniffMimeType,
   tenantExportPrefix,
   tenantStoragePrefixes,
   validateFile,