@cosmicdrift/kumiko-bundled-features 0.333.0 → 0.335.0

package/dist/data-retention/run-retention-cleanup.js

@@ -41,7 +41,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, isSelfPiiField, resolveSubjectForField, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor, createTenantDb, nullBlindIndexesForSubject, } from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
-import { createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
 import { runInSubTransaction } from "../shared/index.js";
 import { computeCutoff } from "./keep-for.js";
@@ -204,22 +204,62 @@ function isFileRefBoundElsewhere(fileRef, entityName, rowId) {
         return true;
     return false;
 }
-// A single-field fileRef-id can be shared by more than one row of the SAME
-// table (e.g. a stock-photo re-picked across records). Purging its bytes
-// would corrupt the row that isn't being deleted. Bounded by batchLimit rows
-// per run and singleFields.length queries per fileRef — the same per-row
-// event-cost tradeoff as the rest of this cron (see header).
-async function isFileRefSharedByOtherRow(db, table, tableHasTenantId, tenantId, rowId, singleFields, fileRefId) {
-    for (const field of singleFields) {
-        const where = { [field]: fileRefId, id: { ne: rowId } };
-        if (tableHasTenantId)
-            where["tenantId"] = tenantId;
-        const others = await selectMany(db, table, where, { limit: 1 });
-        if (others.length > 0)
-            return true;
+// Every implicit entity table with file/image fields: an unbound fileRef
+// (POST /files without entityType/entityId) can sit in single fields of
+// several entity types, so the sharing check must look beyond the purged
+// row's own table.
+function collectSingleFileHolders(registry) {
+    const holders = [];
+    for (const proj of registry.getAllProjections().values()) {
+        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
+            continue;
+        const entity = registry.getEntity(proj.source);
+        if (!entity)
+            continue;
+        const { singleFields } = planFileFields(entity.fields);
+        if (singleFields.length === 0)
+            continue;
+        const table = proj.table; // @cast-boundary column-presence probe
+        holders.push({
+            table: proj.table,
+            tableHasTenantId: table["tenantId"] !== undefined,
+            singleFields,
+        });
+    }
+    return holders;
+}
+// A single-field fileRef-id can be shared by more than one row, in the SAME
+// table (e.g. a stock-photo re-picked across records) or in another entity's
+// table. Purging its bytes would corrupt the row that isn't being deleted.
+// Bounded by batchLimit rows per run and holderFields queries per fileRef —
+// the same per-row event-cost tradeoff as the rest of this cron (see header).
+async function isFileRefSharedByOtherRow(db, holders, ownTable, tenantId, rowId, fileRefId) {
+    for (const holder of holders) {
+        for (const field of holder.singleFields) {
+            const where = { [field]: fileRefId };
+            if (holder.table === ownTable)
+                where["id"] = { ne: rowId };
+            if (holder.tableHasTenantId)
+                where["tenantId"] = tenantId;
+            const others = await selectMany(db, holder.table, where, { limit: 1 });
+            if (others.length > 0)
+                return true;
+        }
     }
     return false;
 }
+// Throws (unsafe key, missing list permission) must fail this row closed,
+// not abort the whole tenant run.
+async function deleteFileFailingClosed(key, store, logContext) {
+    try {
+        return await deleteStoredFileAndDerivatives(key, store, "data-retention:hardDelete");
+    }
+    catch (err) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
+        console.warn(`[data-retention:hardDelete] ${logContext} storage cleanup threw: ${err instanceof Error ? err.message : String(err)}`);
+        return [key];
+    }
+}
 // hardDelete for ONE row of an entity that has file/image/files/images
 // fields: delete the un-shared fileRefs' bytes (+ derivatives) first, then
 // their fileRef rows, then the entity row itself — bytes before rows so a
@@ -251,7 +291,7 @@ async function purgeHardDeleteRowWithFiles(args) {
     for (const fileRef of fileRefRows) {
         if (isFileRefBoundElsewhere(fileRef, args.entityName, rowId))
             continue;
-        const shared = await isFileRefSharedByOtherRow(args.db, args.table, args.tableHasTenantId, args.tenantId, rowId, args.plan.singleFields, String(fileRef["id"]));
+        const shared = await isFileRefSharedByOtherRow(args.db, args.fileHolders, args.table, args.tenantId, rowId, String(fileRef["id"]));
         if (shared)
             continue;
         toDelete.push(fileRef);
@@ -270,7 +310,7 @@ async function purgeHardDeleteRowWithFiles(args) {
         const key = fileRef["storageKey"];
         if (typeof key !== "string" || key.length === 0)
             continue;
-        const failedKeys = await deleteStoredFileAndDerivatives(key, store, "data-retention:hardDelete");
+        const failedKeys = await deleteFileFailingClosed(key, store, `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`);
         if (failedKeys.length > 0) {
             anyFailed = true;
             // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
@@ -295,9 +335,6 @@ async function purgeHardDeleteRowWithFiles(args) {
 // each skip reason at most once per entity per run (repeat skips would just
 // be noise; the per-row failure is already warned above).
 async function purgeHardDeleteRowsWithFiles(args) {
-    const rows = await selectMany(args.db, args.table, args.where, {
-        limit: args.batchLimit,
-    });
     const reasonsSeen = new Set();
     const onSkip = (reason) => {
         // skip: reason already reported for this entity in this run
@@ -306,28 +343,44 @@ async function purgeHardDeleteRowsWithFiles(args) {
         reasonsSeen.add(reason);
         args.skipped.push({ entityName: args.entityName, reason });
     };
+    // id-cursor paging: rows skipped (missing storage, failed delete) stay in the
+    // table, so an unordered limit-page would re-fetch the same stuck rows every
+    // run and starve every row behind them. batchLimit bounds the DELETES.
     let count = 0;
-    for (const row of rows) {
-        const ok = await purgeHardDeleteRowWithFiles({
-            db: args.db,
-            table: args.table,
-            tableHasTenantId: args.tableHasTenantId,
-            tenantId: args.tenantId,
-            entityName: args.entityName,
-            entity: args.entity,
-            row,
-            plan: args.plan,
-            files: args.files,
-            entityExecutor: args.entityExecutor,
-            fileRefExecutor: args.fileRefExecutor,
-            systemUser: args.systemUser,
-            tdb: args.tdb,
-            kms: args.kms,
-            registry: args.registry,
-            onSkip,
+    let cursor = null;
+    while (count < args.batchLimit) {
+        const pageWhere = cursor === null ? args.where : { ...args.where, id: { gt: cursor } };
+        const rows = await selectMany(args.db, args.table, pageWhere, {
+            limit: args.batchLimit,
+            orderBy: { col: "id" },
         });
-        if (ok)
-            count++;
+        if (rows.length === 0)
+            break;
+        for (const row of rows) {
+            cursor = row["id"]; // @cast-boundary db-row
+            const ok = await purgeHardDeleteRowWithFiles({
+                db: args.db,
+                table: args.table,
+                fileHolders: args.fileHolders,
+                tenantId: args.tenantId,
+                entityName: args.entityName,
+                entity: args.entity,
+                row,
+                plan: args.plan,
+                files: args.files,
+                entityExecutor: args.entityExecutor,
+                fileRefExecutor: args.fileRefExecutor,
+                systemUser: args.systemUser,
+                tdb: args.tdb,
+                kms: args.kms,
+                registry: args.registry,
+                onSkip,
+            });
+            if (ok)
+                count++;
+            if (count >= args.batchLimit)
+                break;
+        }
     }
     return count;
 }
@@ -394,6 +447,7 @@ export async function runRetentionCleanup(args) {
     // filter shrinks the set). A single batched forget/delete event is a follow-up.
     const systemUser = createSystemUser(tenantId);
     const tdb = createTenantDb(db, tenantId, "system");
+    const fileHolders = collectSingleFileHolders(registry);
     // Pre-load every override row for this tenant ONCE — N entities × M
     // tenants would otherwise mean one fetchOne per entity per tenant, even
     // though the whole set for a tenant is a single small, indexed read.
@@ -458,7 +512,7 @@ export async function runRetentionCleanup(args) {
                 hardDeleted += await purgeHardDeleteRowsWithFiles({
                     db,
                     table: proj.table,
-                    tableHasTenantId: table["tenantId"] !== undefined,
+                    fileHolders,
                     where,
                     batchLimit,
                     tenantId,
@@ -495,10 +549,12 @@ export async function runRetentionCleanup(args) {
             case "blockDelete": {
                 const targets = await resolveAnonymizeTargets(entity.fields);
                 if (!targets) {
-                    // blockDelete without anonymize fields is a pure hold: a subjectRef-only
-                    // person link outlives the hold and is cut only by the user-data
-                    // forget hook, so expiry has nothing to do here and is not reported.
-                    if (policy.strategy === "anonymize") {
+                    // blockDelete without anonymize fields is a pure hold only while the
+                    // entity has no field that CAN carry anonymize: a subjectRef-only
+                    // person link outlives the hold and is cut by the user-data forget
+                    // hook. A personal field lacking its anonymize function would stay
+                    // stored past the hold, so that case is still reported.
+                    if (policy.strategy === "anonymize" || entityHasAnonymizableSubjectField(entity.fields)) {
                         skipped.push({ entityName, reason: "missing_anonymize_fields" });
                     }
                     break;

package/dist/data-retention/schema/tenant-retention-override.d.ts

@@ -9,6 +9,7 @@ export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -45,6 +46,7 @@ export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -67,6 +69,7 @@ export declare const tenantRetentionOverrideTable: import("@cosmicdrift/kumiko-f
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -103,6 +106,7 @@ export declare const tenantRetentionOverrideTable: import("@cosmicdrift/kumiko-f
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/delivery/tables.d.ts

@@ -12,6 +12,7 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -32,6 +33,7 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -52,6 +54,7 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -78,6 +81,7 @@ export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumik
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -98,6 +102,7 @@ export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumik
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -118,6 +123,7 @@ export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumik
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/delivery/types.d.ts

@@ -23,7 +23,8 @@ export type RenderedMessage = {
     readonly html: string;
     readonly subject: string;
 };
-export type DeliveryChannelMode = "inline" | "queued";
+export declare const DELIVERY_CHANNEL_MODES: readonly ["inline", "queued"];
+export type DeliveryChannelMode = (typeof DELIVERY_CHANNEL_MODES)[number];
 export type DeliveryChannel = {
     readonly name: string;
     readonly mode: DeliveryChannelMode;

package/dist/delivery/types.js

@@ -1,8 +1,15 @@
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
+// `mode` decides how the delivery-service dispatches a channel:
+//   inline — sent synchronously inside notify() (inApp: DB insert + SSE).
+//   queued — sent asynchronously via the delivery.send job; channels with a
+//            render() additionally run through delivery.render first.
+export const DELIVERY_CHANNEL_MODES = ["inline", "queued"];
 export function isDeliveryChannelPlugin(o) {
     return (typeof o === "object" &&
         o !== null &&
         "mode" in o &&
+        DELIVERY_CHANNEL_MODES.some((mode) => mode === o.mode) &&
+        (!("render" in o) || o.render === undefined || typeof o.render === "function") &&
         "resolve" in o &&
         typeof o.resolve === "function" &&
         "send" in o &&

package/dist/delivery/unsubscribe.js

@@ -213,13 +213,7 @@ function confirmationPage(token) {
 // One-click clients put the token in the query string; only the
 // confirmation-page form submits it in the body.
 function tokenFromPostRequest(request) {
-    const contentType = request.headers["content-type"];
-    if (contentType?.includes("application/x-www-form-urlencoded")) {
-        const fromBody = new URLSearchParams(request.rawBody).get("token");
-        if (fromBody)
-            return fromBody;
-    }
-    return request.query["token"];
+    return tokenFromRequestBody(request) ?? request.query["token"];
 }
 // Resubscribe is deliberately NOT reachable via the query string — a mail
 // client's link prefetcher (or a scanner) following an unsubscribe link
@@ -227,10 +221,10 @@ function tokenFromPostRequest(request) {
 // convention is built to avoid; resubscribe carries the same risk in
 // reverse (a prefetch that undoes a real opt-out) and gets no query-param
 // fallback at all.
-function tokenFromResubscribeRequest(request) {
+function tokenFromRequestBody(request) {
     const contentType = request.headers["content-type"];
     if (contentType?.includes("application/x-www-form-urlencoded")) {
-        return new URLSearchParams(request.rawBody).get("token") ?? undefined;
+        return new URLSearchParams(request.rawBody).get("token") || undefined;
     }
     if (contentType?.includes("application/json")) {
         try {
@@ -278,13 +272,13 @@ export function createUnsubscribeRoutes(options) {
         },
     });
     // Undo direction: token only from the JSON/form body, never the query
-    // (see tokenFromResubscribeRequest) — no GET confirmation-page variant,
+    // (see tokenFromRequestBody) — no GET confirmation-page variant,
     // this is a one-shot POST from the unsubscribe-page's "Undo" button.
     const resubscribeRoute = signatureRoute({
         method: "POST",
         path: DELIVERY_RESUBSCRIBE_PATH,
         entry: "signature",
-        verify: async (request) => verifyUnsubscribeToken(tokenFromResubscribeRequest(request), encodedSecret),
+        verify: async (request) => verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret),
         handler: async (c, verified, deps) => {
             const outcome = await dispatchResubscribeWrite(verified, deps);
             if (outcome === "limit_reached") {

package/dist/derivatives-sharp/render.js

@@ -124,24 +124,40 @@ function overlayPosition(gravity, marginPx, outputWidth, outputHeight, layerWidt
 // fraction of the output is a fraction of what the caller actually gets,
 // regardless of the source's own dimensions or `fit` crop.
 async function applyOverlays(pipeline, layers) {
-    const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+    // PNG intermediate: a bare toBuffer() re-encodes in the source format, so a
+    // JPEG source would gain an extra lossy generation before applyEncoder runs.
+    const { data, info } = await pipeline.png().toBuffer({ resolveWithObject: true });
     const composites = [];
     for (const layer of layers) {
+        const targetWidth = Math.max(1, Math.round(info.width * layer.widthPct));
+        // The QR is square, so the output height bounds its side just like the width does.
+        const qrSide = Math.min(targetWidth, info.height);
+        if (layer.kind === "qr" && qrSide < MIN_QR_PIXEL_WIDTH) {
+            throw new Error(`derivatives-sharp: qr overlay would render at ${qrSide}px wide, below the ${MIN_QR_PIXEL_WIDTH}px minimum a camera can reliably scan.`);
+        }
+        // Rendered at its final size so the modules stay hard-edged; resampling a
+        // small default-size QR to a non-integer module size blurs them.
         const layerBytes = layer.kind === "qr"
-            ? await QRCode.toBuffer(layer.data, { margin: 1, errorCorrectionLevel: "M" })
+            ? await QRCode.toBuffer(layer.data, {
+                width: qrSide,
+                margin: 1,
+                errorCorrectionLevel: "M",
+            })
             : Buffer.from(layer.imageBase64, "base64");
         const layerMeta = await sharp(layerBytes, SHARP_INPUT_OPTIONS).metadata();
         assertNotSvg(layerMeta.format);
-        const targetWidth = Math.max(1, Math.round(info.width * layer.widthPct));
-        if (layer.kind === "qr" && targetWidth < MIN_QR_PIXEL_WIDTH) {
-            throw new Error(`derivatives-sharp: qr overlay would render at ${targetWidth}px wide, below the ${MIN_QR_PIXEL_WIDTH}px minimum a camera can reliably scan.`);
-        }
         // PNG (not the layer's own format) to keep any alpha through the resize.
         // height caps the other axis too — sharp's composite() rejects an input
         // larger than the base image, which a tall/square layer would otherwise
         // hit once widthPct alone drives its width past the output's height.
         const resized = await sharp(layerBytes, SHARP_INPUT_OPTIONS)
-            .resize({ width: targetWidth, height: info.height, fit: "inside" })
+            .resize({
+            width: targetWidth,
+            height: info.height,
+            fit: "inside",
+            // Only ever a sub-pixel correction for a QR; keeps module edges crisp.
+            kernel: layer.kind === "qr" ? "nearest" : "lanczos3",
+        })
             .png()
             .toBuffer({ resolveWithObject: true });
         const marginPx = Math.round(info.width * (layer.marginPct ?? 0));
@@ -212,7 +228,8 @@ function assertOverlayLayerBounds(layer) {
     if (!Number.isFinite(layer.widthPct) || layer.widthPct <= 0 || layer.widthPct > 1) {
         throw new Error(`derivatives-sharp: overlay widthPct ${layer.widthPct} is out of range — must be a finite number in (0, 1].`);
     }
-    if (layer.marginPct !== undefined && (layer.marginPct < 0 || layer.marginPct >= 0.5)) {
+    if (layer.marginPct !== undefined &&
+        (!Number.isFinite(layer.marginPct) || layer.marginPct < 0 || layer.marginPct >= 0.5)) {
         throw new Error(`derivatives-sharp: overlay marginPct ${layer.marginPct} is out of range — must be within [0, 0.5).`);
     }
     if (layer.kind === "qr") {
@@ -278,7 +295,8 @@ export const renderImage = async (input, spec, sourceMimeType) => {
     // the output.
     let pipeline = sharp(input, SHARP_INPUT_OPTIONS).rotate();
     if (spec.blurRegions && spec.blurRegions.length > 0) {
-        const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+        // PNG intermediate for the same reason as in applyOverlays (no extra lossy generation).
+        const { data, info } = await pipeline.png().toBuffer({ resolveWithObject: true });
         const blurred = await applyBlurRegions(data, info.width, info.height, spec.blurRegions);
         pipeline = sharp(blurred, SHARP_INPUT_OPTIONS);
     }

package/dist/document-ingest-foundation/entity.d.ts

@@ -20,6 +20,7 @@ export declare const documentExtractEntity: import("@cosmicdrift/kumiko-types/fi
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -40,6 +41,7 @@ export declare const documentExtractEntity: import("@cosmicdrift/kumiko-types/fi
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -79,6 +81,7 @@ export declare const documentExtractsTable: import("@cosmicdrift/kumiko-framewor
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -99,6 +102,7 @@ export declare const documentExtractsTable: import("@cosmicdrift/kumiko-framewor
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/document-ingest-foundation/feature.js

@@ -11,7 +11,7 @@ import { validateDocumentIngestProviderWiring } from "./boot-checks.js";
 import { documentExtractEntity } from "./entity.js";
 import { DOCUMENT_INGEST_AGGREGATE_TYPE, DOCUMENT_INGEST_REQUESTED_EVENT_QN, DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, DOCUMENT_INGEST_SKIPPED_EVENT_QN, DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestRequestedPayloadSchema, documentIngestSkippedPayloadSchema, } from "./events.js";
 import { forgetExtractOnFileRefDeletedHook, forgetExtractOnFileRefForgottenHook, forgetOrphanedDocumentExtractHook, } from "./forget-extract-with-file-ref.js";
-import { EXT_DOCUMENT_INGEST_PROVIDER, resolveDocumentIngestProviders } from "./providers.js";
+import { EXT_DOCUMENT_INGEST_PROVIDER, resolveDocumentIngestProviders, UNCLAIMED_PROVIDER_SENTINEL, } from "./providers.js";
 import { documentExtractTenantDestroyHook } from "./tenant-destroy-hook.js";
 const FEATURE_NAME = "document-ingest-foundation";
 const FILE_REF_CREATED = entityEventName("fileRef", "created");
@@ -123,10 +123,10 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
             {
                 fromVersion: 1,
                 toVersion: 2,
-                // "unknown" can never match a real where.provider filter — an
-                // upcast v1 row reads as unclaimed instead of silently misrouting to
-                // whichever provider happens to be mounted today.
-                transform: { default: { provider: "unknown" } },
+                // 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 } },
             },
         ],
     });

package/dist/document-ingest-foundation/providers.d.ts

@@ -16,6 +16,7 @@ export type ResolvedDocumentIngestProvider = {
     readonly name: string;
     readonly maxFileBytes: number;
 };
+export declare const UNCLAIMED_PROVIDER_SENTINEL = "unknown";
 type ExtensionUsages = FeatureDefinition["extensionUsages"];
 export declare function resolveDocumentIngestProviders(usages: ExtensionUsages): ReadonlyMap<string, ResolvedDocumentIngestProvider>;
 export declare function listIngestibleMimeTypes(registry: Registry): readonly string[];

package/dist/document-ingest-foundation/providers.js

@@ -9,6 +9,9 @@ export const documentIngestProviderOptionsSchema = z.object({
     mimeTypes: z.array(z.string().min(1)).min(1),
     maxFileBytes: z.number().int().positive(),
 });
+// Stamped on upcast v1 documentIngest.requested events; a provider may not
+// claim it, or replayed v1 events would route to that provider.
+export const UNCLAIMED_PROVIDER_SENTINEL = "unknown";
 // Throws on an invalid options shape or two providers claiming the same
 // normalized mimeType — callers decide whether that's boot-fatal.
 export function resolveDocumentIngestProviders(usages) {
@@ -16,6 +19,9 @@ export function resolveDocumentIngestProviders(usages) {
     for (const usage of usages) {
         if (usage.extensionName !== EXT_DOCUMENT_INGEST_PROVIDER)
             continue;
+        if (usage.entityName === UNCLAIMED_PROVIDER_SENTINEL) {
+            throw new Error(`document-ingest-foundation: provider name "${UNCLAIMED_PROVIDER_SENTINEL}" is reserved for upcast legacy events.`);
+        }
         const parsed = documentIngestProviderOptionsSchema.safeParse(usage.options);
         if (!parsed.success) {
             throw new Error(`document-ingest-foundation: provider "${usage.entityName}" registered invalid options via ` +

package/dist/document-ingest-foundation/write-document-extract.d.ts

@@ -1,12 +1,12 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
-import type { DocumentExtractMeta, IngestPage } from "./entity.js";
+import { type DocumentExtractMeta, type IngestPage } from "./entity.js";
 export type DocumentExtractWriteResult = {
     readonly kind: "written";
     readonly documentExtractId: string;
 } | {
     readonly kind: "skipped";
-    readonly reason: "file_ref_deleted";
+    readonly reason: "file_ref_deleted" | "already_extracted";
 };
 export declare function writeDocumentExtractForLiveFileRef(input: {
     readonly tenantDb: TenantDb;

package/dist/document-ingest-foundation/write-document-extract.js

@@ -3,6 +3,7 @@
 // the one place that write must go through to stay race-safe against a
 // concurrent fileRef delete/forget — see forget-extract-with-file-ref.ts.
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { documentExtractsTable } from "./entity.js";
 import { documentExtractExecutor } from "./executor.js";
 import { isFileRefLive } from "./file-ref-liveness.js";
 import { writeIngestPages } from "./pages.js";
@@ -13,6 +14,15 @@ export async function writeDocumentExtractForLiveFileRef(input) {
     if (!(await isFileRefLive(input.tenantDb, input.fileRefId))) {
         return { kind: "skipped", reason: "file_ref_deleted" };
     }
+    // A redelivered documentIngest.requested, or the one a delete→restore race
+    // re-requests while the old extract is still standing, must not create a
+    // second extract for the same fileRef.
+    const existing = await input.tenantDb.selectMany(documentExtractsTable, {
+        fileRefId: input.fileRefId,
+    });
+    if (existing.length > 0) {
+        return { kind: "skipped", reason: "already_extracted" };
+    }
     const result = await documentExtractExecutor.create({
         fileRefId: input.fileRefId,
         storageKey: input.storageKey,

package/dist/feature-toggles/global-feature-state-table.js

@@ -1,4 +1,4 @@
-import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import { boolean, declareGlobalTenancy, instant, integer, table as pgTable, sql, text, } from "@cosmicdrift/kumiko-framework/db";
 // Global feature-toggle override state. One row per feature that has ever
 // been explicitly flipped by an operator. Missing row = "no override,
@@ -26,9 +26,4 @@ export const globalFeatureStateTable = declareGlobalTenancy(pgTable("store_globa
 // the pgTable made queries type-check while the migration generator stayed
 // blind to it, failing in prod with "column ... does not exist" while every
 // mocked-stack test stayed green.
-const derivedMeta = asEntityTableMeta(globalFeatureStateTable);
-if (!derivedMeta) {
-    throw new Error("global-feature-state-table: asEntityTableMeta(globalFeatureStateTable) returned undefined " +
-        "— the pgTable definition no longer round-trips through the unmanaged-table meta builder.");
-}
-export const globalFeatureStateTableMeta = derivedMeta;
+export const globalFeatureStateTableMeta = requireEntityTableMeta(globalFeatureStateTable, "globalFeatureStateTable");

package/dist/feature-toggles/toggle-sync-signal.d.ts

@@ -1,5 +1,6 @@
+import { type RedisClientOptions } from "@cosmicdrift/kumiko-framework/redis";
 import type { ToggleSyncSignal } from "./toggle-runtime.js";
 export type RedisToggleSyncSignal = ToggleSyncSignal & {
     close(): Promise<void>;
 };
-export declare function createRedisToggleSyncSignal(redisUrl: string): RedisToggleSyncSignal;
+export declare function createRedisToggleSyncSignal(redisUrl: string, clientOptions?: RedisClientOptions): RedisToggleSyncSignal;

package/dist/feature-toggles/toggle-sync-signal.js

@@ -1,4 +1,4 @@
-import { createRedisPubSubSignal } from "@cosmicdrift/kumiko-framework/redis";
+import { createRedisPubSubSignal, } from "@cosmicdrift/kumiko-framework/redis";
 // Single fixed channel — unlike the SSE broker there's no per-tenant/
 // per-user variance to multiplex, every toggle flip is global.
 const TOGGLE_SYNC_CHANNEL = "kumiko:feature-toggles:cache-sync";
@@ -15,11 +15,12 @@ function isTogglePayload(value) {
 // replicas > 1 is expected to set REDIS_URL, so app-boot code should build
 // this only when REDIS_URL is present and pass it into
 // createFeatureToggleRuntime.
-export function createRedisToggleSyncSignal(redisUrl) {
+export function createRedisToggleSyncSignal(redisUrl, clientOptions) {
     const signal = createRedisPubSubSignal({
         redisUrl,
         channelPattern: TOGGLE_SYNC_CHANNEL,
         label: "feature-toggles",
+        ...(clientOptions ? { clientOptions } : {}),
     });
     return {
         publish(featureName, enabled) {

package/dist/file-provider-s3/feature.js

@@ -36,7 +36,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
     r.requires("secrets");
     r.requires("file-foundation");
     const secretAccessKey = r.secret("s3.secretAccessKey", {
-        label: { en: "S3 Secret Access Key" },
+        label: { en: "S3 secret access key" },
         hint: {
             en: "Private half of the S3 key pair. Hetzner calls it 'Secret Key', AWS calls it 'Secret Access Key'.",
         },

package/dist/files-tenant-data/index.js

@@ -13,6 +13,7 @@
 import { defineFeature, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/engine";
 import { sweepOrphanedDerivativesJob, sweepOrphanedDerivativesPayloadSchema, } from "./handlers/sweep-orphaned-derivatives.job.js";
 import { fileRefStorageDestroyHook, fileRefTenantDestroyHook } from "./hooks.js";
+const SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON = "iterates every tenant and checks fileRef owners per tenant";
 export function createFilesTenantDataFeature() {
     return defineFeature("files-tenant-data", (r) => {
         r.describe("GDPR coverage for the `files` feature's `fileRef` entity: tenant-destroy row purge (EXT_TENANT_DATA) and full storage-prefix binary wipe (EXT_STORAGE_PROVIDER), plus a manual backfill/GC job that sweeps derivatives orphaned by a forget/tenant-destroy that ran before #2461 wired binary cleanup into those flows. Requires `tenant-lifecycle`, optionalRequires `files`.");
@@ -31,9 +32,9 @@ export function createFilesTenantDataFeature() {
             concurrency: "skip",
             schema: sweepOrphanedDerivativesPayloadSchema,
             escapeHatch: {
-                reason: "iterates every tenant and checks fileRef owners per tenant",
+                reason: SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON,
             },
-            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw("iterates every tenant and checks fileRef owners per tenant")),
+            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw(SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON)),
         });
     });
 }