@cosmicdrift/kumiko-framework 0.393.0 → 0.395.0

package/dist/files/create-file-ref.d.ts

@@ -1,7 +1,7 @@
-import type { AnyFileFieldDef } from "@cosmicdrift/kumiko-types/fields";
 import type { TenantDb } from "../db/tenant-db.ts";
 import type { Registry, SessionUser } from "../engine/types/index.ts";
 import { type WriteFailure } from "../errors/index.ts";
+import { type AttachTargets } from "./upload-field-resolution.ts";
 export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
 declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
     readonly id: string;
@@ -23,15 +23,6 @@ declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event
     readonly storageKey: string;
 }>;
 export declare function getFileRefExecutor(): ReturnType<typeof buildFileRefExecutor>;
-type AttachedFieldResolution = {
-    readonly kind: "unattached";
-} | {
-    readonly kind: "resolved";
-    readonly fieldDef: AnyFileFieldDef;
-} | {
-    readonly kind: "unresolvable";
-};
-export declare function resolveAttachedField(registry: Registry | undefined, entityType: string | undefined, fieldName: string | undefined): AttachedFieldResolution;
 export type StoreFileInput = {
     readonly fileName: string;
     readonly declaredMimeType: string;
@@ -48,7 +39,8 @@ export type StoreFileDeps = {
     readonly tenantDb: TenantDb;
     readonly rowInOwnTransaction?: boolean;
     readonly registry: Registry | undefined;
-    readonly defaultMaxUploadSize: string;
+    readonly attachTargets?: AttachTargets;
+    readonly defaultMaxUploadSize: string | number;
     readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
     readonly deleteBytes: (storageKey: string) => Promise<void>;
     readonly isAttachTargetLocked?: (rowDb: TenantDb) => Promise<boolean>;
@@ -88,7 +80,7 @@ export type StoreFileOutcome = {
     readonly kind: "failed";
     readonly failure: WriteFailure;
 };
-export declare function writeAcceptedFileBytes(deps: Pick<StoreFileDeps, "user" | "registry" | "defaultMaxUploadSize" | "writeBytes">, input: StoreFileInput): Promise<UploadBytesOutcome>;
+export declare function writeAcceptedFileBytes(deps: Pick<StoreFileDeps, "user" | "registry" | "attachTargets" | "defaultMaxUploadSize" | "writeBytes">, input: StoreFileInput): Promise<UploadBytesOutcome>;
 export declare function createFileRefRow(deps: Pick<StoreFileDeps, "user" | "tenantDb">, uploaded: UploadedFileBytes): Promise<{
     readonly fileRef: CreatedFileRef;
 } | {

package/dist/files/create-file-ref.js

@@ -1,13 +1,12 @@
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { runInOwnTransaction } from "../db/tenant-db-scoped-rebind.js";
-import { isFileField } from "../engine/field-helpers.js";
 import { InternalError } from "../errors/index.js";
 import { generateId } from "../utils/index.js";
-import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 import { resolveContentType } from "./resolve-content-type.js";
 import { buildStorageKey, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+import { resolveUploadField } from "./upload-field-resolution.js";
 import { takeUploadLedgerEntry } from "./upload-ledger.js";
 export const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
 // Standard entity executor for fileRef: create/delete emit fileRef.created /
@@ -26,50 +25,8 @@ export function getFileRefExecutor() {
 }
 const ACTION_FORM_STORAGE_SEGMENT = "action-form";
 const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
-// entityType/fieldName drive the GDPR-forget decision downstream
-// (fileRefDeleteHook resolves the field's PII annotation from exactly this
-// pairing) — attaching to a field nobody can resolve would leave that
-// decision hanging on an unverified client string. Either both are omitted
-// (unattached upload, allowed) or both must resolve to a real registered
-// field.
-export function resolveAttachedField(registry, entityType, fieldName) {
-    if (entityType === undefined && fieldName === undefined)
-        return { kind: "unattached" };
-    const entity = entityType !== undefined ? registry?.getEntity(entityType) : undefined;
-    const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
-    if (!entityType || !fieldName || !entity || !fieldDef || !isFileField(fieldDef))
-        return { kind: "unresolvable" };
-    return { kind: "resolved", fieldDef };
-}
 class AttachTargetLockedError extends Error {
 }
-function resolveUploadField(registry, input) {
-    const { entityType, entityId, fieldName, actionForm } = input;
-    if (actionForm === undefined)
-        return resolveAttachedField(registry, entityType, fieldName);
-    if (entityType !== undefined || entityId !== undefined) {
-        return {
-            kind: "rejected",
-            error: "invalid_action_form: actionForm cannot be combined with entityType/entityId",
-        };
-    }
-    if (!isActionFormScreenQn(actionForm)) {
-        return {
-            kind: "rejected",
-            error: "invalid_action_form: expected a screen QN like <feature>:screen:<id>",
-        };
-    }
-    const fieldDef = fieldName !== undefined
-        ? resolveActionFormFileField(registry, actionForm, fieldName)
-        : undefined;
-    if (fieldDef === undefined) {
-        return {
-            kind: "rejected",
-            error: "unresolvable_field: actionForm and fieldName must name a files/image field of a registered actionForm screen",
-        };
-    }
-    return { kind: "resolved", fieldDef };
-}
 function acceptFile(deps, input) {
     const { fileName, declaredMimeType, data, entityType, entityId, fieldName } = input;
     const rejected = (error) => ({ kind: "rejected", error });
@@ -85,7 +42,7 @@ function acceptFile(deps, input) {
             return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
         }
     }
-    const field = resolveUploadField(deps.registry, input);
+    const field = resolveUploadField(deps.registry, input, deps.attachTargets);
     if (field.kind === "rejected")
         return field;
     if (field.kind === "unresolvable") {

package/dist/files/default-file-guard.d.ts

@@ -0,0 +1,4 @@
+import type { FileAccessGuard } from "./file-routes.ts";
+import type { RecordReadCheck } from "./record-read-check.ts";
+export declare const DEFAULT_PRIVILEGED_ROLES: readonly ["Admin", "SystemAdmin"];
+export declare function createDefaultGuard(privilegedRoles: readonly string[], canReadRecord: RecordReadCheck | undefined, unclaimedUploadReaders: readonly string[], recordOnlyEntityTypes: ReadonlySet<string>): FileAccessGuard;

package/dist/files/default-file-guard.js

@@ -0,0 +1,41 @@
+import { SYSTEM_USER_ID } from "../engine/system-user.js";
+export const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
+// Default guard: on attached files, allow the uploader or a privileged role,
+// and for reads also everyone who may read the record. Delete stays with the
+// uploader and privileged roles: reading a record is no right to remove its
+// files. Pending uploads (entityType set, record not yet created) are the
+// uploader's own until bound; so are uploads without an entityType, which no
+// record can ever claim.
+export function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReaders, recordOnlyEntityTypes) {
+    return async ({ fileRef, user, operation }) => {
+        if (fileRef.insertedById === user.id)
+            return "allow";
+        const isRecordOnly = fileRef.entityType !== null && recordOnlyEntityTypes.has(fileRef.entityType);
+        if (!isRecordOnly && hasAnyRole(user, privilegedRoles))
+            return "allow";
+        if (isUnclaimedUpload(fileRef) &&
+            operation === "read" &&
+            hasAnyRole(user, unclaimedUploadReaders)) {
+            return "allow";
+        }
+        if (fileRef.entityType === null || fileRef.entityId === null)
+            return "deny";
+        if (operation !== "read" || canReadRecord === undefined)
+            return "deny";
+        const recordReadable = await canReadRecord({
+            entityType: fileRef.entityType,
+            entityId: fileRef.entityId,
+            user,
+        });
+        return recordReadable ? "allow" : "deny";
+    };
+}
+function hasAnyRole(user, roles) {
+    return roles.some((role) => user.roles.includes(role));
+}
+// System-generated documents are created without attachTo too, but belong to a person's data, not to an inbox.
+function isUnclaimedUpload(fileRef) {
+    return (fileRef.entityType === null &&
+        fileRef.entityId === null &&
+        fileRef.insertedById !== SYSTEM_USER_ID);
+}

package/dist/files/delete-record-file-refs.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "../db/tenant-db.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+export declare function deleteFileRefsBoundToRecord(args: {
+    readonly db: TenantDb;
+    readonly user: SessionUser;
+    readonly entityType: string;
+    readonly entityId: string;
+}): Promise<number>;

package/dist/files/delete-record-file-refs.js

@@ -0,0 +1,20 @@
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefsTable } from "./file-ref-table.js";
+// Same soft delete as DELETE /files/:id for every fileRef bound to one record, for owners that
+// remove the record without an r.entity delete (a retention sweep over a projection read model).
+export async function deleteFileRefsBoundToRecord(args) {
+    const { db, user, entityType, entityId } = args;
+    const rows = await db.selectMany(fileRefsTable, {
+        entityType,
+        entityId,
+        isDeleted: false,
+    });
+    const executor = getFileRefExecutor();
+    for (const row of rows) {
+        const removed = await executor.delete({ id: row.id }, user, db);
+        if (!removed.isSuccess)
+            throw reraiseAsKumikoError(removed.error);
+    }
+    return rows.length;
+}

package/dist/files/file-routes.d.ts

@@ -43,5 +43,6 @@ export type FileRoutesOptions = {
 };
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
 export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "unclaimedUploadReaders" | "maxUploadSize">;
+export declare function configuredMaxUploadBytes(registry: Registry): number | undefined;
 export declare function createFileRoutes(options: FileRoutesOptions): Hono;
 export {};

package/dist/files/file-routes.js

@@ -11,14 +11,16 @@ import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveRenderer } from "../derivatives/derivatives-context.js";
 import { resolveFieldVariant } from "../derivatives/index.js";
 import { isFileField } from "../engine/field-helpers.js";
-import { isAnonymousSessionUser, SYSTEM_USER_ID } from "../engine/system-user.js";
+import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { createFailOpenReporter, respondRateLimited } from "../rate-limit/middleware.js";
 import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
+import { createDefaultGuard, DEFAULT_PRIVILEGED_ROLES } from "./default-file-guard.js";
 import { createFileContext, createTenantFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
+import { collectRecordOnlyFileEntityTypes } from "./record-only-file-entity-types.js";
 import { isStoredRecordLocked, RecordWriteDecisions, } from "./record-write-check.js";
 import { neutralFileNameForMimeType } from "./resolve-content-type.js";
 import { parseMaxSize, resolveServedContentType } from "./types.js";
@@ -29,7 +31,10 @@ export function deleteFailureResponseFor(error) {
     const status = isOneOf(ERROR_STATUSES, error.httpStatus) ? error.httpStatus : 500;
     return { status, code: status === 404 ? "not_found" : error.code };
 }
-const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
+// 401 (not 403) lets the client tell a revoked or expired session from a missing permission.
+function unauthenticatedUploadResponse(c) {
+    return c.json({ error: "unauthenticated: sign in to upload files", code: "unauthenticated" }, 401);
+}
 // 15 minutes — long enough for a download to start, short enough that a
 // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
 // credential (see "Signed-URL default expiry" in core-files.md).
@@ -39,39 +44,6 @@ const META_BATCH_IDS_PER_WINDOW = 1_000;
 const META_BATCH_WINDOW_SECONDS = 60;
 // Each detail() read decrypts through the KMS pool; a bounded chunk keeps one batch from hogging it.
 const BATCH_META_CONCURRENCY = 10;
-// Default guard: on attached files, allow the uploader or a privileged role,
-// and for reads also everyone who may read the record. Delete stays with the
-// uploader and privileged roles: reading a record is no right to remove its
-// files. Pending uploads (entityType set, record not yet created) are the
-// uploader's own until bound; so are uploads without an entityType, which no
-// record can ever claim.
-function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReaders) {
-    return async ({ fileRef, user, operation }) => {
-        if (fileRef.insertedById === user.id)
-            return "allow";
-        if (privilegedRoles.some((role) => user.roles.includes(role)))
-            return "allow";
-        // System-generated documents are created without attachTo too, but belong to a person's data, not to an inbox.
-        const isUnclaimedUpload = fileRef.entityType === null &&
-            fileRef.entityId === null &&
-            fileRef.insertedById !== SYSTEM_USER_ID;
-        if (isUnclaimedUpload &&
-            operation === "read" &&
-            unclaimedUploadReaders.some((role) => user.roles.includes(role))) {
-            return "allow";
-        }
-        if (fileRef.entityType === null || fileRef.entityId === null)
-            return "deny";
-        if (operation !== "read" || canReadRecord === undefined)
-            return "deny";
-        const recordReadable = await canReadRecord({
-            entityType: fileRef.entityType,
-            entityId: fileRef.entityId,
-            user,
-        });
-        return recordReadable ? "allow" : "deny";
-    };
-}
 // Multipart framing plus the small entityType/entityId/fieldName parts
 // riding alongside the file.
 const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
@@ -106,6 +78,11 @@ export function readFilesRouteOptions(registry) {
     }
     return {};
 }
+// Explicitly configured global upload limit in bytes; undefined when createFilesFeature set none.
+export function configuredMaxUploadBytes(registry) {
+    const configured = readFilesRouteOptions(registry).maxUploadSize;
+    return configured === undefined ? undefined : parseMaxSize(configured);
+}
 export function createFileRoutes(options) {
     const { db, metaBatchRateLimitResolver } = options;
     const reportMetaBatchLimiterFailOpen = createFailOpenReporter("files-meta-batch");
@@ -115,7 +92,7 @@ export function createFileRoutes(options) {
         : withUploadLedger(options.resolveProvider, db);
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
     const guard = options.accessGuard ??
-        createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? []);
+        createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? [], options.registry ? collectRecordOnlyFileEntityTypes(options.registry) : new Set());
     const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
@@ -171,6 +148,10 @@ export function createFileRoutes(options) {
     // POST /files — multipart upload.
     api.post("/files", uploadBodyLimit, async (c) => {
         const user = getUser(c);
+        // Anonymous visitors share one user id and cannot bind pending uploads (bind-pending-file-refs),
+        // so an anonymous upload could never be used; 401 lets the client tell an ended session apart.
+        if (isAnonymousSessionUser(user))
+            return unauthenticatedUploadResponse(c);
         const body = await c.req.parseBody();
         const file = body["file"];
         if (!file || !(file instanceof File)) {
@@ -188,11 +169,11 @@ export function createFileRoutes(options) {
         }
         // Before any bytes are written, like the record check below. An unresolvable screen falls
         // through to storeFileAsFileRef, which answers 400; a known one must be submittable by the
-        // caller. Anonymous callers cannot bind pending uploads, so they get no upload either.
+        // caller.
         if (actionForm !== undefined &&
             options.registry !== undefined &&
             options.registry.getScreen(actionForm)?.type === "actionForm" &&
-            (isAnonymousSessionUser(user) || !mayUseActionForm(options.registry, actionForm, user))) {
+            !mayUseActionForm(options.registry, actionForm, user)) {
             return c.json({ error: "forbidden: no access to this form" }, 403);
         }
         if (entityId !== undefined) {

package/dist/files/index.d.ts

@@ -1,15 +1,19 @@
 export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.ts";
 export type { PendingFileRef } from "./bind-pending-file-refs.ts";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
+export type { CanReadFileRefContext } from "./can-caller-read-file-ref.ts";
+export { canCallerReadFileRef } from "./can-caller-read-file-ref.ts";
 export type { CreatedFileRef, CreateFileRefInput, UploadedFileBytes, } from "./create-file-ref-from-bytes.ts";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";
+export { createDefaultGuard } from "./default-file-guard.ts";
+export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";
 export type { FileContext } from "./file-handle.ts";
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.ts";
 export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.ts";
 export { fileRefsTable } from "./file-ref-table.ts";
-export type { FileAccessGuard } from "./file-routes.ts";
-export { readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.ts";
+export type { FileAccessGuard, FileRef } from "./file-routes.ts";
+export { configuredMaxUploadBytes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.ts";
 export type { InMemoryFileProvider } from "./in-memory-provider.ts";
 export { createInMemoryFileProvider } from "./in-memory-provider.ts";
 export { createLocalProvider } from "./local-provider.ts";

package/dist/files/index.js

@@ -1,13 +1,16 @@
 export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.js";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
+export { canCallerReadFileRef } from "./can-caller-read-file-ref.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
+export { createDefaultGuard } from "./default-file-guard.js";
+export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.js";
 export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefsTable } from "./file-ref-table.js";
-export { readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
+export { configuredMaxUploadBytes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
 export { createInMemoryFileProvider } from "./in-memory-provider.js";
 export { createLocalProvider } from "./local-provider.js";
 export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.js";

package/dist/files/record-only-file-entity-types.d.ts

@@ -0,0 +1,2 @@
+import type { Registry } from "../engine/types/index.ts";
+export declare function collectRecordOnlyFileEntityTypes(registry: Registry): ReadonlySet<string>;

package/dist/files/record-only-file-entity-types.js

@@ -0,0 +1,22 @@
+const cache = new WeakMap();
+// Event-sourced read models (projection entities) are not in getAllEntities, so both sources count.
+export function collectRecordOnlyFileEntityTypes(registry) {
+    const cached = cache.get(registry);
+    if (cached)
+        return cached;
+    const entityTypes = new Set();
+    for (const [name, entity] of registry.getAllEntities()) {
+        if (entity.attachedFileAccess === "record-only")
+            entityTypes.add(name);
+    }
+    for (const projection of registry.getAllProjections().values()) {
+        const name = projection.source;
+        if (typeof name !== "string")
+            continue;
+        if (registry.getReadModelEntity(name)?.attachedFileAccess === "record-only") {
+            entityTypes.add(name);
+        }
+    }
+    cache.set(registry, entityTypes);
+    return entityTypes;
+}

package/dist/files/record-read-check.js

@@ -17,6 +17,17 @@ function buildDetailQueryIndex(registry) {
             detailQueryByEntity.set(entityName, qn);
         }
     }
+    for (const projection of registry.getAllProjections().values()) {
+        const entityName = projection.source;
+        if (typeof entityName !== "string")
+            continue;
+        const owner = registry.getReadModelEntityOwner(entityName);
+        if (owner === undefined)
+            continue;
+        const qn = `${owner}:query:${toKebab(entityName)}:detail`;
+        if (registry.getAllQueryHandlers().has(qn))
+            detailQueryByEntity.set(entityName, qn);
+    }
     return detailQueryByEntity;
 }
 // "May this user read the record?" is answered by the entity's own detail

package/dist/files/types.d.ts

@@ -7,7 +7,8 @@ export type FileMetadata = {
 };
 export type { FileStorageProvider, SignedUrlOptions, WriteStreamOptions, } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
 export type FileValidationOptions = {
-    readonly maxSize?: string | undefined;
+    /** "10mb"-style string or a byte count. */
+    readonly maxSize?: string | number | undefined;
     readonly accept?: readonly string[] | undefined;
 };
 export declare function parseMaxSize(maxSize: string): number;

package/dist/files/types.js

@@ -175,7 +175,7 @@ export function resolveServedContentType(bytes, declaredMimeType) {
 }
 export function validateFile(metadata, options) {
     if (options.maxSize) {
-        const maxBytes = parseMaxSize(options.maxSize);
+        const maxBytes = typeof options.maxSize === "number" ? options.maxSize : parseMaxSize(options.maxSize);
         if (metadata.size > maxBytes) {
             return `file_too_large: ${metadata.size} bytes exceeds ${options.maxSize}`;
         }

package/dist/files/upload-field-resolution.d.ts

@@ -0,0 +1,24 @@
+import type { AnyFileFieldDef } from "@cosmicdrift/kumiko-types/fields";
+import type { Registry } from "../engine/types/index.ts";
+type UploadTarget = {
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+    readonly actionForm?: string | undefined;
+};
+export type AttachTargets = "entities" | "entities-and-read-models";
+type AttachedFieldResolution = {
+    readonly kind: "unattached";
+} | {
+    readonly kind: "resolved";
+    readonly fieldDef: AnyFileFieldDef;
+} | {
+    readonly kind: "unresolvable";
+};
+export declare function resolveAttachedField(registry: Registry | undefined, entityType: string | undefined, fieldName: string | undefined, attachTargets?: AttachTargets): AttachedFieldResolution;
+type UploadFieldResolution = AttachedFieldResolution | {
+    readonly kind: "rejected";
+    readonly error: string;
+};
+export declare function resolveUploadField(registry: Registry | undefined, input: UploadTarget, attachTargets: AttachTargets | undefined): UploadFieldResolution;
+export {};

package/dist/files/upload-field-resolution.js

@@ -0,0 +1,51 @@
+import { isFileField } from "../engine/field-helpers.js";
+import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
+// entityType/fieldName drive the GDPR-forget decision downstream
+// (fileRefDeleteHook resolves the field's PII annotation from exactly this
+// pairing) — attaching to a field nobody can resolve would leave that
+// decision hanging on an unverified client string. Either both are omitted
+// (unattached upload, allowed) or both must resolve to a real registered
+// field. "entities-and-read-models" is for server-side callers only: a client upload must
+// never name a projection entity, whose rows nobody can write-check.
+export function resolveAttachedField(registry, entityType, fieldName, attachTargets = "entities") {
+    if (entityType === undefined && fieldName === undefined)
+        return { kind: "unattached" };
+    const entity = entityType !== undefined
+        ? (registry?.getEntity(entityType) ??
+            (attachTargets === "entities-and-read-models"
+                ? registry?.getReadModelEntity(entityType)
+                : undefined))
+        : undefined;
+    const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
+    if (!entityType || !fieldName || !entity || !fieldDef || !isFileField(fieldDef))
+        return { kind: "unresolvable" };
+    return { kind: "resolved", fieldDef };
+}
+export function resolveUploadField(registry, input, attachTargets) {
+    const { entityType, entityId, fieldName, actionForm } = input;
+    if (actionForm === undefined) {
+        return resolveAttachedField(registry, entityType, fieldName, attachTargets);
+    }
+    if (entityType !== undefined || entityId !== undefined) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: actionForm cannot be combined with entityType/entityId",
+        };
+    }
+    if (!isActionFormScreenQn(actionForm)) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: expected a screen QN like <feature>:screen:<id>",
+        };
+    }
+    const fieldDef = fieldName !== undefined
+        ? resolveActionFormFileField(registry, actionForm, fieldName)
+        : undefined;
+    if (fieldDef === undefined) {
+        return {
+            kind: "rejected",
+            error: "unresolvable_field: actionForm and fieldName must name a files/image field of a registered actionForm screen",
+        };
+    }
+    return { kind: "resolved", fieldDef };
+}

package/dist/jobs/job-runner-event-triggers.d.ts

@@ -0,0 +1,12 @@
+import type { Tracer } from "@cosmicdrift/kumiko-types/observability";
+import type { Queue } from "bullmq";
+import type { JobRunIn, Registry } from "../engine/types/index.ts";
+import { type JobRunnerScope } from "./job-runner-scope.ts";
+import type { JobRunner } from "./job-runner-types.ts";
+export type JobEventTriggerDeps = {
+    readonly scope: JobRunnerScope;
+    readonly queues: Readonly<Record<JobRunIn, Queue>>;
+    readonly tracer: Tracer;
+    readonly allJobs: ReturnType<Registry["getAllJobs"]>;
+};
+export declare function createJobEventTriggers(deps: JobEventTriggerDeps): Pick<JobRunner, "handleEvent" | "handleCatchUpEvent">;

package/dist/jobs/job-runner-event-triggers.js

@@ -0,0 +1,64 @@
+import { requestContext } from "../api/request-context.js";
+import { buildRetryBullOpts, captureTraceContext, catchUpJobId, eventTriggerMatches, stampGatedWriteOrigin, TRACE_CONTEXT_KEY, } from "./job-runner-helpers.js";
+import { announceQueued, isOverPerTenantLimit, laneForJob, } from "./job-runner-scope.js";
+import { resolveMaxPerTenant } from "./max-per-tenant.js";
+export function createJobEventTriggers(deps) {
+    const { scope, queues, tracer, allJobs } = deps;
+    async function enqueueEventTriggeredJob(name, jobDef, eventName, payload, user, triggerEvent, jobId) {
+        // Same correlation propagation as dispatch(): the job keeps the causal chain.
+        const traceCtx = captureTraceContext(tracer);
+        const reqCtx = requestContext.get();
+        const data = { ...payload };
+        if (user) {
+            data["_tenantId"] = user.tenantId;
+            data["_triggeredById"] = user.id;
+        }
+        // _triggerName tells a multi-trigger handler which trigger fired; set for single triggers too.
+        data["_triggerName"] = eventName;
+        if (triggerEvent)
+            data["_triggerEvent"] = triggerEvent;
+        if (traceCtx)
+            data[TRACE_CONTEXT_KEY] = traceCtx;
+        if (reqCtx?.correlationId)
+            data["_correlationId"] = reqCtx.correlationId;
+        // Same maxPerTenant guard as dispatch — events that fan into many
+        // jobs must respect the per-tenant cap or the limit is one-sided.
+        const maxPerTenant = resolveMaxPerTenant(jobDef);
+        if (maxPerTenant?.onLimit === "skip" && user?.tenantId !== undefined) {
+            if (await isOverPerTenantLimit(scope, name, String(user.tenantId), maxPerTenant.limit)) {
+                // skip: onLimit "skip" drops this trigger on purpose while the tenant is at its cap.
+                return;
+            }
+        }
+        stampGatedWriteOrigin(data);
+        const bullOpts = { ...buildRetryBullOpts(jobDef) };
+        if (jobId !== undefined)
+            bullOpts.jobId = jobId;
+        // Route to the job's declared lane, not a fixed queue.
+        const job = await queues[laneForJob(jobDef)].add(name, data, bullOpts);
+        await announceQueued(scope, name, jobDef, job, data);
+    }
+    return {
+        async handleEvent(eventName, payload, user, triggerEvent) {
+            for (const [name, jobDef] of allJobs) {
+                if (!("on" in jobDef.trigger) || jobDef.trigger.catchUp)
+                    continue;
+                // skip: other trigger types (cron, manual) do not respond to events;
+                // catchUp jobs are fed by their own consumer (handleCatchUpEvent).
+                if (!eventTriggerMatches(jobDef.trigger, eventName, payload))
+                    continue;
+                await enqueueEventTriggeredJob(name, jobDef, eventName, payload, user, triggerEvent);
+            }
+        },
+        async handleCatchUpEvent(jobName, eventName, payload, user, triggerEvent) {
+            const jobDef = allJobs.get(jobName);
+            // A stale consumer for a removed or changed job, or an event the trigger filters out, runs nothing.
+            if (jobDef &&
+                "on" in jobDef.trigger &&
+                jobDef.trigger.catchUp &&
+                eventTriggerMatches(jobDef.trigger, eventName, payload)) {
+                await enqueueEventTriggeredJob(jobName, jobDef, eventName, payload, user, triggerEvent, catchUpJobId(jobName, triggerEvent.id));
+            }
+        },
+    };
+}

package/dist/jobs/job-runner-helpers.d.ts

@@ -46,6 +46,11 @@ export declare function timeoutReject(ms: number, message: string): {
 };
 export declare function buildRetryBullOpts(jobDef: JobDefinition, priorAttempts?: number): Pick<JobsOptions, "attempts" | "backoff">;
 export declare function payloadMatchesTriggerFilter(where: Readonly<Record<string, string | number | boolean>> | undefined, payload: Record<string, unknown>): boolean;
+type EventJobTrigger = Extract<JobDefinition["trigger"], {
+    readonly on: unknown;
+}>;
+export declare function eventTriggerMatches(trigger: EventJobTrigger, eventName: string, payload: Record<string, unknown>): boolean;
+export declare function catchUpJobId(jobName: string, eventId: string): string;
 export declare const COMPLETED_JOB_RETENTION_AGE_SEC = 86400;
 export declare const FAILED_JOB_RETENTION_AGE_SEC = 604800;
 export declare function maxRetryWindowMs(jobDef: JobDefinition): number;

package/dist/jobs/job-runner-helpers.js

@@ -272,6 +272,16 @@ export function payloadMatchesTriggerFilter(where, payload) {
         return true;
     return Object.entries(where).every(([key, value]) => payload[key] === value);
 }
+export function eventTriggerMatches(trigger, eventName, payload) {
+    const matches = Array.isArray(trigger.on)
+        ? trigger.on.includes(eventName)
+        : trigger.on === eventName;
+    return matches && payloadMatchesTriggerFilter(trigger.where, payload);
+}
+// BullMQ rejects ":" in custom ids; job QNs and event ids contain them or dashes.
+export function catchUpJobId(jobName, eventId) {
+    return `catchup.${jobName.replaceAll(":", ".")}.${eventId}`;
+}
 // BullMQ sweeps queue-wide: any job finishing with keepJobs set can evict
 // OTHER jobs in the same completed/failed zset (moveToFinished lua,
 // removeJobsByMaxAge/removeJobsByMaxCount), not just the finishing job, and

package/dist/jobs/job-runner-types.d.ts

@@ -42,6 +42,7 @@ export type JobRunner = {
     stop(): Promise<void>;
     dispatch(jobName: string, payload?: Record<string, unknown>, meta?: JobMeta): Promise<string>;
     handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
+    handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
     attachDispatcher(ref: DispatchWriteRef): void;
     countPendingJobs(): Promise<number>;
 };