@cosmicdrift/kumiko-samples 0.367.0 → 0.368.0

package/packages/bundled-features/src/delivery/handlers/log.query.ts

@@ -1,8 +1,9 @@
-import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   decodeKeysetCursor,
   encodeKeysetCursor,
+  selectMany,
   type TenantDb,
+  type WhereObject,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -66,7 +67,7 @@ function isDeliveryLogSortField(value: string): value is DeliveryLogSortField {
 type DeliveryLogSortColumn = (typeof DELIVERY_LOG_SORT_COLUMNS)[DeliveryLogSortField];
 
 // createdAt round-trips through Temporal.Instant (matches how the WHERE
-// builder coerces timestamptz values — see bun-db/query.ts prepareValue);
+// builder coerces timestamptz values — see db/query.ts prepareValue);
 // every other whitelisted column is a plain text column. Keyed by the
 // PHYSICAL column, not the display alias — row only has the DB field names
 // (e.g. notificationType), never the alias (e.g. "type").

package/packages/bundled-features/src/delivery/handlers/preferences.query.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/packages/bundled-features/src/delivery/upsert-preference.ts

@@ -13,8 +13,11 @@
 // fall through to update, or no-op if the winner already set the target
 // `enabled` state.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  fetchOne,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
 import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.js";

package/packages/bundled-features/src/derivatives-sharp/feature.ts

@@ -6,17 +6,26 @@ import { renderImage } from "./render.js";
 
 const FEATURE_NAME = "derivatives-sharp";
 
-export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+export function createDerivativesSharpFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+      );
+      r.uiHints({
+        displayLabel: "File Derivatives · Sharp",
+        category: "storage",
+        recommended: false,
+      });
+      r.requires({ features: ["file-derivatives"] });
+
+      const plugin: DerivativeRendererPlugin = { render: renderImage };
+      r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
+    },
+    { dedupeOptions: {} },
   );
-  r.uiHints({
-    displayLabel: "File Derivatives · Sharp",
-    category: "storage",
-    recommended: false,
-  });
-  r.requires({ features: ["file-derivatives"] });
+}
 
-  const plugin: DerivativeRendererPlugin = { render: renderImage };
-  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
-});
+/** @deprecated Use createDerivativesSharpFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const derivativesSharpFeature = createDerivativesSharpFeature();

package/packages/bundled-features/src/derivatives-sharp/index.ts

@@ -1,2 +1,2 @@
-export { derivativesSharpFeature } from "./feature.js";
+export { createDerivativesSharpFeature, derivativesSharpFeature } from "./feature.js";
 export { imageMetadata } from "./render.js";

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -121,108 +121,117 @@ async function requestIngestForFileRef(
   });
 }
 
-export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
-  );
-  r.uiHints({
-    displayLabel: "Document Ingest Foundation",
-    category: "storage",
-    recommended: false,
-  });
-  // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
-  // tenant-subject ciphertext and needs the destroy hook below.
-  r.requires({ features: ["config", "tenant-lifecycle"] });
-
-  r.entity({ name: "documentExtract", ...documentExtractEntity });
-  r.useExtension(EXT_TENANT_DATA, "documentExtract", {
-    destroy: documentExtractTenantDestroyHook,
-  });
-
-  // No onRegister: resolution happens at boot and per-apply, not on register.
-  r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
-  r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
-
-  const ocrLanguageConfigKey = r.config(
-    "ocrLanguage",
-    createTenantConfig("text", {
-      default: "deu+eng",
-      // Tesseract -l argument syntax: one or more 3-letter language codes
-      // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
-      // reach the OCR provider call unvalidated (#1501).
-      pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-  const maxPagesPerFileConfigKey = r.config(
-    "maxPagesPerFile",
-    createTenantConfig("number", {
-      default: 50,
-      // Without a bound a tenant could set 0 (silently kills ingest) or an
-      // unbounded value (OCR worker runs per-file for as long as the PDF
-      // has pages — job-queue starvation) (#1501).
-      bounds: { min: 1, max: 500 },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-
-  // "fileName" can carry a real person's name, but it reaches both events already as the
-  // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
-  // append() passes through; shredding the fileRef's key shreds it here too.
-  r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
-    piiFields: "none",
-    version: 2,
-    migrations: [
-      {
-        fromVersion: 1,
-        toVersion: 2,
-        // The sentinel can never match a real where.provider filter (providers
-        // may not register under it) — an upcast v1 row reads as unclaimed
-        // instead of silently misrouting to a currently mounted provider.
-        transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
-      },
-    ],
-  });
-  r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
-    piiFields: "none",
-  });
-
-  r.multiStreamProjection({
-    name: "request-ingest",
-    apply: {
-      [FILE_REF_CREATED]: async (event, _tx, ctx) => {
-        // entity-event payloads are generic Record<string, unknown> — parse
-        // at the MSP boundary (same pattern as storage-tracking's readNumber).
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
-        // skip: malformed / incomplete payload — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-      [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
-        // fileRef.restored carries { previous }, the pre-restore soft-deleted
-        // row (event-store-executor-write.ts restore()) — same field shape
-        // as fileRef.created's payload.
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
-        // skip: malformed / incomplete previous snapshot — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-    },
-  });
-
-  // fileRef delete/forget cleanup: documentExtract rows are derived data —
-  // once the source file is gone (soft-deleted or Art.17-forgotten), the
-  // extracted text has no reason to survive it either.
-  r.multiStreamProjection({
-    name: "forget-extract-with-file-ref",
-    apply: {
-      [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
-      [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
-      [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+export function createDocumentIngestFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
+      );
+      r.uiHints({
+        displayLabel: "Document Ingest Foundation",
+        category: "storage",
+        recommended: false,
+      });
+      // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
+      // tenant-subject ciphertext and needs the destroy hook below.
+      r.requires({ features: ["config", "tenant-lifecycle"] });
+
+      r.entity({ name: "documentExtract", ...documentExtractEntity });
+      r.useExtension(EXT_TENANT_DATA, "documentExtract", {
+        destroy: documentExtractTenantDestroyHook,
+      });
+
+      // No onRegister: resolution happens at boot and per-apply, not on register.
+      r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
+      r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
+
+      const ocrLanguageConfigKey = r.config(
+        "ocrLanguage",
+        createTenantConfig("text", {
+          default: "deu+eng",
+          // Tesseract -l argument syntax: one or more 3-letter language codes
+          // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
+          // reach the OCR provider call unvalidated (#1501).
+          pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+      const maxPagesPerFileConfigKey = r.config(
+        "maxPagesPerFile",
+        createTenantConfig("number", {
+          default: 50,
+          // Without a bound a tenant could set 0 (silently kills ingest) or an
+          // unbounded value (OCR worker runs per-file for as long as the PDF
+          // has pages — job-queue starvation) (#1501).
+          bounds: { min: 1, max: 500 },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+
+      // "fileName" can carry a real person's name, but it reaches both events already as the
+      // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
+      // append() passes through; shredding the fileRef's key shreds it here too.
+      r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
+        piiFields: "none",
+        version: 2,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            // The sentinel can never match a real where.provider filter (providers
+            // may not register under it) — an upcast v1 row reads as unclaimed
+            // instead of silently misrouting to a currently mounted provider.
+            transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
+          },
+        ],
+      });
+      r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
+        piiFields: "none",
+      });
+
+      r.multiStreamProjection({
+        name: "request-ingest",
+        apply: {
+          [FILE_REF_CREATED]: async (event, _tx, ctx) => {
+            // entity-event payloads are generic Record<string, unknown> — parse
+            // at the MSP boundary (same pattern as storage-tracking's readNumber).
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
+            // skip: malformed / incomplete payload — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+          [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
+            // fileRef.restored carries { previous }, the pre-restore soft-deleted
+            // row (event-store-executor-write.ts restore()) — same field shape
+            // as fileRef.created's payload.
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
+            // skip: malformed / incomplete previous snapshot — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+        },
+      });
+
+      // fileRef delete/forget cleanup: documentExtract rows are derived data —
+      // once the source file is gone (soft-deleted or Art.17-forgotten), the
+      // extracted text has no reason to survive it either.
+      r.multiStreamProjection({
+        name: "forget-extract-with-file-ref",
+        apply: {
+          [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
+          [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
+          [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+        },
+      });
+
+      return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
     },
-  });
+    { dedupeOptions: {} },
+  );
+}
 
-  return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
-});
+/** @deprecated Use createDocumentIngestFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const documentIngestFoundationFeature = createDocumentIngestFoundationFeature();

package/packages/bundled-features/src/document-ingest-foundation/forget-extract-with-file-ref.ts

@@ -57,7 +57,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
   const parsed = documentExtractCreatedPayloadSchema.safeParse(event.payload);
   // skip: malformed payload — don't poison the consumer
   if (!parsed.success) return;
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef still live — the extract is legitimate
   if (await isFileRefLive(tenantDb, parsed.data.fileRefId)) return;
   const user = createSystemUser(event.tenantId);
@@ -70,7 +70,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef is live again — request-ingest and this consumer poll via
   // separate cursors, so a delete→restore round-trip can finish before this
   // consumer sees fileRef.deleted; forgetting would drop the live file's extract.
@@ -79,6 +79,6 @@ export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefForgottenHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   await forgetExtractsForFileRef(event, tenantDb);
 };

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -18,7 +18,10 @@ export {
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.js";
-export { documentIngestFoundationFeature } from "./feature.js";
+export {
+  createDocumentIngestFoundationFeature,
+  documentIngestFoundationFeature,
+} from "./feature.js";
 export { readIngestPages, writeIngestPages } from "./pages.js";
 export {
   type DocumentIngestProviderOptions,

package/packages/bundled-features/src/feature-toggles/global-feature-state-table.ts

@@ -1,4 +1,3 @@
-import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
   declareGlobalTenancy,
@@ -6,6 +5,7 @@ import {
   instant,
   integer,
   table as pgTable,
+  requireEntityTableMeta,
   type SchemaTable,
   sql,
   text,

package/packages/bundled-features/src/feature-toggles/handlers/set.write.ts

@@ -1,4 +1,4 @@
-import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,
@@ -158,10 +158,8 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
       // and filtering by payload.featureName is trivial at query time.
       // This mirrors how `config` handles the same constraint for
       // its config-changed events.
-      // unsafeAppendEvent — bundled-features ohne lokalen Wrapper. Apps
-      // mit `bun kumiko codegen` kriegen `.kumiko/define.ts` als strict-
-      // path; bundled-features bleibt bei der unsafe-Variante. Schema-
-      // Validation läuft trotzdem via r.defineEvent("toggle-set", ...).
+      // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
+      // bundled-features cannot see. Schema validation still runs via r.defineEvent("toggle-set", ...).
       await ctx.unsafeAppendEvent({
         aggregateId: SYSTEM_TENANT_ID,
         aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,

package/packages/bundled-features/src/feature-toggles/toggle-runtime.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   computeEffectiveFeatures,
   type Registry,