@cosmicdrift/kumiko-framework 0.359.0 → 0.361.0

package/dist/files/dispose-removed-file-refs.js

@@ -0,0 +1,51 @@
+import { isFileField, } from "../engine/types/index.js";
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+function isBoundTo(row, entityName, entityId, fieldName) {
+    return (row["entityType"] === entityName &&
+        row["entityId"] === entityId &&
+        row["fieldName"] === fieldName);
+}
+// An update that drops or replaces a file id leaves the fileRef readable to
+// everyone who may read the record. Deleting it goes through the same executor
+// path as DELETE /files/:id (soft delete, bytes kept until retention), so
+// record readers get 404 afterwards. Only fileRefs bound to exactly this
+// record and field are touched: an id that is pending, shared or bound
+// elsewhere is not this save's to dispose. The authority is the caller's write
+// right on the record (the fileRef entity declares no write access of its own).
+export async function disposeRemovedFileRefs(args) {
+    const { registry, result, user, db } = args;
+    // skip: a create has no earlier files that could be removed
+    if (result.isNew)
+        return;
+    // skip: saves of unnamed aggregates declare no file fields
+    if (result.entityName === undefined)
+        return;
+    const entityName = result.entityName;
+    const entity = registry.getEntity(entityName);
+    // skip: saves of unregistered aggregates (custom executors) declare no file fields
+    if (entity === undefined)
+        return;
+    // skip: without the files feature the file_refs table is not part of the schema
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        return;
+    const entityId = String(result.id);
+    const executor = getFileRefExecutor();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef) || !(fieldName in result.changes))
+            continue;
+        const kept = new Set(fileRefIdsOf(result.data[fieldName]));
+        for (const fileRefId of fileRefIdsOf(result.previous[fieldName])) {
+            if (kept.has(fileRefId))
+                continue;
+            const row = await executor.detail({ id: fileRefId }, user, db);
+            if (row === null || !isBoundTo(row, entityName, entityId, fieldName))
+                continue;
+            const removed = await executor.delete({ id: fileRefId }, user, db);
+            if (!removed.isSuccess)
+                throw reraiseAsKumikoError(removed.error);
+        }
+    }
+}

package/dist/files/feature.js

@@ -1,5 +1,5 @@
 import { defineFeature } from "../engine/index.js";
-import { fileRefEntity } from "./file-ref-entity.js";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
 // den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
@@ -20,7 +20,7 @@ export function createFilesFeature(options = {}) {
             category: "storage",
             recommended: false,
         });
-        r.entity("fileRef", fileRefEntity);
+        r.entity(FILE_REF_ENTITY_NAME, fileRefEntity);
         return { routeOptions: options };
     });
 }

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

@@ -1,3 +1,4 @@
+export { FILE_REF_ENTITY_NAME } from "./types.js";
 export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     storageKey: {
         readonly type: "text";

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

@@ -17,6 +17,7 @@ import { createBigIntField, createEntity, createTextField } from "../engine/inde
 //     reference: "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). The other
 //     fields (storageKey, mimeType, entityType, entityId, fieldName) are
 //     technical references or system metadata, not subject content.
+export { FILE_REF_ENTITY_NAME } from "./types.js";
 export const fileRefEntity = createEntity({
     table: "file_refs",
     softDelete: true,

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

@@ -1,5 +1,5 @@
 import { buildEntityTable } from "../db/table-builder.js";
-import { fileRefEntity } from "./file-ref-entity.js";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 // `file_refs` ist die read-table des `fileRef`-Entity. Aus der Entity-
 // Definition gebaut (kein hand-gepflegtes pgTable mehr), damit die implizite
 // Entity-Projektion (Rebuild) und der Live-Executor-Write spaltengleich auf
@@ -9,4 +9,4 @@ import { fileRefEntity } from "./file-ref-entity.js";
 // jeder Upload appended `fileRef.created`, jeder Delete `fileRef.deleted`
 // (Standard-Entity-Auto-Verben). UUIDs schließen die Enumeration-Attacke
 // auf /files/:id.
-export const fileRefsTable = buildEntityTable("fileRef", fileRefEntity);
+export const fileRefsTable = buildEntityTable(FILE_REF_ENTITY_NAME, fileRefEntity);

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

@@ -2,6 +2,8 @@ import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.js";
 import type { FileProviderResolver } from "./provider-resolver.js";
+import type { RecordReadCheck } from "./record-read-check.js";
+import { type RecordWriteCheck } from "./record-write-check.js";
 export type FileAccessDecision = "allow" | "deny";
 export type FileRef = {
     id: string;
@@ -27,6 +29,8 @@ export type FileRoutesOptions = {
     readonly maxUploadSize?: string;
     readonly privilegedRoles?: readonly string[];
     readonly accessGuard?: FileAccessGuard;
+    readonly canReadRecord?: RecordReadCheck;
+    readonly canWriteRecord?: RecordWriteCheck;
 };
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
 export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;

package/dist/files/file-routes.js

@@ -4,54 +4,46 @@ import { getUser } from "../api/auth-middleware.js";
 import { requestContext } from "../api/request-context.js";
 import { selectMany } from "../bun-db/index.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
-import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { createTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
-import { generateId } from "../utils/index.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
+import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
-import { neutralFileNameForMimeType, resolveContentType } from "./resolve-content-type.js";
-import { buildStorageKey, parseMaxSize, resolveServedContentType, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+import { RecordWriteDecisions } from "./record-write-check.js";
+import { neutralFileNameForMimeType } from "./resolve-content-type.js";
+import { parseMaxSize, resolveServedContentType } from "./types.js";
 const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
 // 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).
 const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
-// Default guard: on attached files, allow the uploader or a privileged role.
-// Unattached files are tenant-wide (the tenant boundary is already enforced
-// by the query).
-function createDefaultGuard(privilegedRoles) {
-    return ({ fileRef, user }) => {
-        if (fileRef.entityType === null || fileRef.entityId === null)
-            return "allow";
+// 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) {
+    return async ({ fileRef, user, operation }) => {
         if (fileRef.insertedById === user.id)
             return "allow";
-        for (const role of privilegedRoles) {
-            if (user.roles.includes(role))
-                return "allow";
-        }
-        return "deny";
+        if (privilegedRoles.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";
     };
 }
-// 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.
-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 };
-}
-const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
 // Multipart framing plus the small entityType/entityId/fieldName parts
 // riding alongside the file.
 const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
@@ -85,14 +77,8 @@ export function readFilesRouteOptions(registry) {
 export function createFileRoutes(options) {
     const { db } = options;
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
-    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
-    // Standard entity executor for fileRef — self-contained (table + entity).
-    // create/delete emit fileRef.created/deleted and write file_refs via
-    // applyEntityEvent in one tx (read-your-own-write), exactly like any other
-    // entity's lifecycle. The registry only feeds custom projections on those events.
-    const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
-        entityName: "fileRef",
-    });
+    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles, options.canReadRecord);
+    const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
     const projectionGrants = options.registry ? { projectionRegistry: options.registry } : undefined;
@@ -151,103 +137,51 @@ export function createFileRoutes(options) {
         // store it in the text entityId column.
         const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
         const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
-        // These interpolate directly into the storage key (buildStorageKey below) —
-        // reject anything but a safe identifier so a client can't path-traverse
-        // out of its tenant's storage prefix (../.. segments, absolute paths).
-        for (const [field, value] of [
-            ["entityType", entityType],
-            ["entityId", entityId],
-            ["fieldName", fieldName],
-        ]) {
-            if (value !== undefined && !/^[A-Za-z0-9_-]+$/.test(value)) {
-                return c.json({ error: `invalid_${field}: must match /^[A-Za-z0-9_-]+$/` }, 400);
+        if (entityId !== undefined) {
+            if (entityType === undefined) {
+                return c.json({ error: "missing_entity_type: entityId requires entityType" }, 400);
             }
-        }
-        // Validate against entity field definition if available.
-        let maxSize = options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
-        let accept;
-        const attachedField = resolveAttachedField(options.registry, entityType, fieldName);
-        if (attachedField.kind === "unresolvable") {
-            return c.json({
-                error: "unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload",
-            }, 400);
-        }
-        if (attachedField.kind === "resolved") {
-            if (attachedField.fieldDef.maxSize)
-                maxSize = attachedField.fieldDef.maxSize;
-            if (attachedField.fieldDef.accept)
-                accept = attachedField.fieldDef.accept;
-        }
-        const validationError = validateFile({ fileName: file.name, mimeType: file.type, size: file.size }, { maxSize, accept });
-        if (validationError) {
-            return c.json({ error: validationError }, 400);
-        }
-        const data = new Uint8Array(await file.arrayBuffer());
-        const contentValidation = validateFileContent(file.name, data, accept);
-        if (contentValidation.kind === "rejected") {
-            return c.json({ error: contentValidation.error }, 400);
-        }
-        // A normalized upload's real type is already known from the sniffed
-        // bytes — resolveUploadMimeType's alias/rewrite step only applies to the
-        // declared mimeType of an unnormalized upload.
-        let mimeType;
-        if (contentValidation.kind === "normalized") {
-            mimeType = contentValidation.mimeType;
-        }
-        else {
-            const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
-            if (mimeTypeResolution.kind === "rejected") {
-                return c.json({ error: mimeTypeResolution.error }, 400);
+            // Before any bytes are written: a rejected attach must leave no file behind. An
+            // unregistered entityType attaches to nothing; storeFileAsFileRef rejects it with 400.
+            const decision = options.registry !== undefined && options.registry.getEntity(entityType) === undefined
+                ? RecordWriteDecisions.writable
+                : options.canWriteRecord
+                    ? await options.canWriteRecord({ entityType, entityId, fieldName, user })
+                    : RecordWriteDecisions.forbidden;
+            switch (decision) {
+                case RecordWriteDecisions.writable:
+                    break;
+                case RecordWriteDecisions.notFound:
+                    return c.json({ error: "not_found" }, 404);
+                case RecordWriteDecisions.forbidden:
+                    return c.json({ error: "forbidden: no write access to this record" }, 403);
+                case RecordWriteDecisions.locked:
+                    return c.json({ error: "record_locked: the record is locked" }, 409);
             }
-            mimeType = resolveContentType({
-                declared: mimeTypeResolution.mimeType,
-                bytes: data,
-                filename: file.name,
-            });
         }
-        const fileRefId = generateId();
-        const storageKey = buildStorageKey(user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", file.name, generateId(), contentValidation.kind === "normalized" ? contentValidation.extension : undefined);
-        // 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 data = new Uint8Array(await file.arrayBuffer());
         const storageProvider = await options.resolveProvider(user.tenantId);
-        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
-        // explicit so the response + storageKey stay consistent; tenantId,
-        // insertedAt and insertedById are set by applyEntityEvent from the event
-        // metadata. The binary was written above, outside the tx — a create
-        // failure orphans bytes (cleanup-job sweeps) rather than committing a row
-        // whose binary is missing.
-        const result = await executor.create({
-            id: fileRefId,
-            storageKey,
-            fileName: file.name,
-            mimeType,
-            size: file.size,
-            entityType: entityType ?? null,
-            entityId: entityId ?? null,
-            fieldName: fieldName ?? null,
-        }, user, tenantDbFor(user.tenantId));
-        if (!result.isSuccess) {
+        const outcome = await storeFileAsFileRef({
+            user,
+            tenantDb: tenantDbFor(user.tenantId),
+            registry: options.registry,
+            defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+            writeBytes: (key, bytes, mimeType) => storageProvider.write(key, bytes, mimeType),
+            deleteBytes: (key) => storageProvider.delete(key),
+        }, { fileName: file.name, declaredMimeType: file.type, data, entityType, entityId, fieldName });
+        if (outcome.kind === "rejected")
+            return c.json({ error: outcome.error }, 400);
+        if (outcome.kind === "failed")
             return c.json({ error: "upload_failed" }, 500);
-        }
-        return c.json({
-            id: fileRefId,
-            fileName: file.name,
-            mimeType,
-            size: file.size,
-            storageKey,
-        }, 201);
+        return c.json(outcome.fileRef, 201);
     });
     // GET /files/:id — download.
     //
     // Authorization stack:
     //   1. tenantId must match (hard isolation, never crossable).
     //   2. The configured FileAccessGuard decides read access. Default:
-    //      unattached → allow; attached → uploader or privileged role.
+    //      unattached → allow; attached → uploader, privileged role or a
+    //      reader of the record.
     //      Apps override via options.accessGuard to layer entity-level rules.
     api.get("/files/:id", async (c) => {
         const user = getUser(c);

package/dist/files/index.d.ts

@@ -1,3 +1,5 @@
+export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, } from "./create-file-ref-from-bytes.js";
+export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.

package/dist/files/purge-expired-file-ref-bytes.d.ts

@@ -0,0 +1,14 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
+import type { Logger } from "@cosmicdrift/kumiko-types/logger";
+import { deleteMany, type WhereObject } from "../db/query.js";
+import type { TenantDb } from "../db/tenant-db.js";
+export declare const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+type PurgeLog = Pick<Logger, "warn"> | undefined;
+export declare function purgeExpiredFileRefsWithBytes(args: {
+    readonly db: TenantDb;
+    readonly table: Parameters<typeof deleteMany>[1];
+    readonly where: WhereObject;
+    readonly files: FileContext | undefined;
+    readonly log: PurgeLog;
+}): Promise<void>;
+export {};

package/dist/files/purge-expired-file-ref-bytes.js

@@ -0,0 +1,34 @@
+import { deleteMany, selectMany } from "../db/query.js";
+import { deleteStoredFileAndDerivatives } from "../derivatives/delete-stored-file.js";
+export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+// Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
+// rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
+// row whose bytes could not be removed stays and the next run retries it.
+export async function purgeExpiredFileRefsWithBytes(args) {
+    const { db, table, where, files, log } = args;
+    if (!files) {
+        log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
+        return;
+    }
+    const rows = await selectMany(db, table, where, {
+        orderBy: [{ col: "deletedAt", direction: "asc" }],
+        limit: EXPIRED_FILE_REF_PURGE_BATCH,
+    });
+    const purgedIds = [];
+    const store = { list: files.list, delete: (key) => files.ref(key).delete() };
+    for (const row of rows) {
+        try {
+            const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
+            if (failedKeys.length === 0) {
+                purgedIds.push(row.id);
+                continue;
+            }
+            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
+        }
+        catch (err) {
+            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (purgedIds.length > 0)
+        await deleteMany(db, table, { ...where, id: { in: purgedIds } });
+}

package/dist/files/record-read-check.d.ts

@@ -0,0 +1,9 @@
+import type { Registry, SessionUser } from "../engine/types/index.js";
+export type RecordReadCheck = (args: {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly user: SessionUser;
+}) => Promise<boolean>;
+type QueryAsUser = (type: string, payload: unknown, user: SessionUser) => Promise<unknown>;
+export declare function createRecordReadCheck(registry: Registry, query: QueryAsUser): RecordReadCheck;
+export {};

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

@@ -0,0 +1,49 @@
+import { toKebab } from "../engine/qualified-name.js";
+import { isKumikoError } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/index.js";
+const log = createFallbackLogger("files");
+// Only the "<entity>:detail" handler counts: other "<entity>:...:detail"
+// queries map to the same entity but may return a different shape or scope.
+// Entity names are globally unique and only the owning feature maps handlers
+// to its entity, so at most one QN matches per entity.
+function isEntityDetailQuery(qn, entityName) {
+    return qn.endsWith(`:query:${toKebab(entityName)}:detail`);
+}
+function buildDetailQueryIndex(registry) {
+    const detailQueryByEntity = new Map();
+    for (const qn of registry.getAllQueryHandlers().keys()) {
+        const entityName = registry.getHandlerEntity(qn);
+        if (entityName !== undefined && isEntityDetailQuery(qn, entityName)) {
+            detailQueryByEntity.set(entityName, qn);
+        }
+    }
+    return detailQueryByEntity;
+}
+// "May this user read the record?" is answered by the entity's own detail
+// query run as that user: handler access, row ownership and parent visibility
+// all apply, exactly as when the record is opened. null (not found or not
+// visible) and access errors mean no. Entities without a detail query never
+// grant access this way.
+export function createRecordReadCheck(registry, query) {
+    let detailQueryByEntity;
+    return async ({ entityType, entityId, user }) => {
+        detailQueryByEntity ??= buildDetailQueryIndex(registry);
+        const detailQuery = detailQueryByEntity.get(entityType);
+        if (detailQuery === undefined)
+            return false;
+        try {
+            const record = await query(detailQuery, { id: entityId }, user);
+            return record !== null && record !== undefined;
+        }
+        catch (error) {
+            if (!isKumikoError(error) || error.httpStatus >= 500) {
+                log.error("record read check failed; file access denied", {
+                    entityType,
+                    detailQuery,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return false;
+        }
+    };
+}

package/dist/files/record-write-check.d.ts

@@ -0,0 +1,21 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import type { Registry, SessionUser, TenantId } from "../engine/types/index.js";
+import type { RecordReadCheck } from "./record-read-check.js";
+export declare const RecordWriteDecisions: {
+    readonly writable: "writable";
+    readonly notFound: "not_found";
+    readonly forbidden: "forbidden";
+    readonly locked: "locked";
+};
+export type RecordWriteDecision = (typeof RecordWriteDecisions)[keyof typeof RecordWriteDecisions];
+export type RecordWriteCheck = (args: {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly fieldName: string | undefined;
+    readonly user: SessionUser;
+}) => Promise<RecordWriteDecision>;
+export declare function createRecordWriteCheck(args: {
+    readonly registry: Registry;
+    readonly canReadRecord: RecordReadCheck;
+    readonly tenantDbFor: (tenantId: TenantId) => TenantDb;
+}): RecordWriteCheck;

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

@@ -0,0 +1,64 @@
+import { hasAccess } from "../engine/access.js";
+import { normalizeAccessEntry, userCanWriteFieldRow } from "../engine/ownership.js";
+import { toKebab } from "../engine/qualified-name.js";
+import { isRecordLocked } from "../engine/screen-helpers.js";
+export const RecordWriteDecisions = {
+    writable: "writable",
+    notFound: "not_found",
+    forbidden: "forbidden",
+    locked: "locked",
+};
+function isEntityUpdateWrite(qn, entityName) {
+    return qn.endsWith(`:write:${toKebab(entityName)}:update`);
+}
+// "May this user attach a file to the record?" asks what saving the record would ask: the
+// entity's update handler, the row-level and field-level write rules against the stored row,
+// and the lock. Not-readable, foreign-tenant and missing records answer alike (not_found) so
+// the upload never confirms what exists.
+export function createRecordWriteCheck(args) {
+    const { registry, canReadRecord, tenantDbFor } = args;
+    function findUpdateHandlerAccess(entityType) {
+        for (const [qn, handler] of registry.getAllWriteHandlers()) {
+            if (registry.getHandlerEntity(qn) === entityType && isEntityUpdateWrite(qn, entityType)) {
+                return handler.access;
+            }
+        }
+        return undefined;
+    }
+    function findEntityTable(entityType) {
+        for (const projection of registry.getAllProjections().values()) {
+            if (projection.isImplicit === true && projection.source === entityType) {
+                return projection.table;
+            }
+        }
+        return undefined;
+    }
+    return async ({ entityType, entityId, fieldName, user }) => {
+        if (!(await canReadRecord({ entityType, entityId, user }))) {
+            return RecordWriteDecisions.notFound;
+        }
+        const entity = registry.getEntity(entityType);
+        const table = findEntityTable(entityType);
+        if (!entity || !table)
+            return RecordWriteDecisions.notFound;
+        // The stored row, not the detail output: the detail query can hide ownership fields.
+        const row = await tenantDbFor(user.tenantId).fetchOne(table, {
+            id: entityId,
+            ...(entity.softDelete === true && { isDeleted: false }),
+        });
+        if (!row)
+            return RecordWriteDecisions.notFound;
+        if (!hasAccess(user, findUpdateHandlerAccess(entityType)))
+            return RecordWriteDecisions.forbidden;
+        if (!userCanWriteFieldRow(user, entity.access?.write, row, row)) {
+            return RecordWriteDecisions.forbidden;
+        }
+        const fieldWriteRules = fieldName === undefined ? undefined : entity.fields[fieldName]?.access?.write;
+        if (!userCanWriteFieldRow(user, normalizeAccessEntry(fieldWriteRules), row, row)) {
+            return RecordWriteDecisions.forbidden;
+        }
+        if (isRecordLocked(entity.lockedWhen, row))
+            return RecordWriteDecisions.locked;
+        return RecordWriteDecisions.writable;
+    };
+}

package/dist/files/types.d.ts

@@ -1,4 +1,5 @@
 import type { TenantId } from "../engine/types/identifiers.js";
+export declare const FILE_REF_ENTITY_NAME = "fileRef";
 export type FileMetadata = {
     readonly fileName: string;
     readonly mimeType: string;

package/dist/files/types.js

@@ -1,3 +1,6 @@
+// Lives here (not in file-ref-entity.ts) so engine code can name the entity without importing
+// a module that calls createEntity at load time.
+export const FILE_REF_ENTITY_NAME = "fileRef";
 export function parseMaxSize(maxSize) {
     const match = maxSize.match(/^(\d+)(kb|mb|gb)$/i);
     if (!match)

package/dist/i18n/required-surface-keys.js

@@ -162,6 +162,12 @@ function pushRelatedListSectionKeys(out, section) {
     for (const label of Object.values(section.groupBy?.labels ?? {}))
         pushKey(out, label);
 }
+function pushListEmptyStateKeys(out, emptyState) {
+    pushKey(out, emptyState?.title);
+    pushKey(out, emptyState?.description);
+    if (emptyState?.action !== undefined)
+        pushRowActionKeys(out, emptyState.action);
+}
 function pushExpandableRowKeys(out, section) {
     pushRelatedListSectionKeys(out, section);
     for (const action of section.actions ?? [])
@@ -192,6 +198,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             }
             pushKey(out, list.createLabel);
             pushKey(out, list.searchPlaceholder);
+            pushKey(out, list.description);
+            pushListEmptyStateKeys(out, list.emptyState);
             for (const action of list.rowActions ?? [])
                 pushRowActionKeys(out, action);
             for (const action of list.toolbarActions ?? [])
@@ -210,6 +218,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             }
             pushKey(out, list.createLabel);
             pushKey(out, list.searchPlaceholder);
+            pushKey(out, list.description);
+            pushListEmptyStateKeys(out, list.emptyState);
             for (const action of list.rowActions ?? [])
                 pushRowActionKeys(out, action);
             for (const action of list.toolbarActions ?? [])

package/dist/jobs/cron-repeat-options.d.ts

@@ -0,0 +1,9 @@
+export type CronTrigger = {
+    readonly cron: string;
+    readonly tz?: string | undefined;
+};
+export type CronRepeatOptions = {
+    readonly pattern: string;
+    readonly tz?: string;
+};
+export declare function cronRepeatOptions(trigger: CronTrigger): CronRepeatOptions;

package/dist/jobs/cron-repeat-options.js

@@ -0,0 +1,5 @@
+export function cronRepeatOptions(trigger) {
+    return trigger.tz === undefined
+        ? { pattern: trigger.cron }
+        : { pattern: trigger.cron, tz: trigger.tz };
+}