@cosmicdrift/kumiko-framework 0.360.0 → 0.361.0

package/dist/engine/index.d.ts

@@ -80,7 +80,7 @@ export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUse
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/schema-builder.js

@@ -409,8 +409,8 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
 // Field types whose column is nullable and whose projection write accepts a
 // plain `null`. Excluded: select/writeOnly text (fieldToZod is already
 // nullable there), and types where null would not clear cleanly — NOT NULL
-// jsonb columns (multiSelect, embedded, jsonb, multi reference), files/images
-// (no column; stripped from updates), locatedTimestamp (split into _utc/_tz
+// jsonb columns (multiSelect, embedded, jsonb, multi reference, files/images),
+// locatedTimestamp (split into _utc/_tz
 // columns, a bare null targets a column that does not exist) and money (the
 // currency column would keep its stale value).
 const NULL_CLEARABLE_FIELD_TYPES = new Set([

package/dist/engine/screen-helpers.d.ts

@@ -25,6 +25,7 @@ export declare function normalizeListColumn(c: ListColumnSpec): Exclude<ListColu
  *  (form-condition closures) reuse it; three hand-rolled copies had
  *  already drifted in shape. */
 export declare function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean;
+export declare function isRecordLocked(lockedWhen: FieldCondition | undefined, row: Readonly<Record<string, unknown>>): boolean;
 type SelectOptionRules = Pick<SelectFieldDef, "options" | "conditionalOptions">;
 export type UnavailableSelectOption = {
     readonly field: string;

package/dist/engine/screen-helpers.js

@@ -110,6 +110,15 @@ export function evalFieldCondition(cond, values) {
         return !cond.notIn.includes(val);
     return val !== cond.ne;
 }
+// A row that lacks the condition's field counts as locked: an unreadable lock state
+// must not open the record.
+export function isRecordLocked(lockedWhen, row) {
+    if (lockedWhen === undefined)
+        return false;
+    if (typeof lockedWhen === "object" && !(lockedWhen.field in row))
+        return true;
+    return evalFieldCondition(lockedWhen, { ...row });
+}
 /** Options of a select field that are offered for the given row values, in declaration order. */
 export function availableSelectOptions(field, values) {
     const rules = field.conditionalOptions;

package/dist/engine/soft-delete-cleanup.js

@@ -11,6 +11,8 @@
 // table growth; irreversible event-log purging is data-retention's job
 // (pruneEvents), a separate, consumer-lag-guarded path.
 import { asEntityTableMeta, deleteMany } from "../db/query.js";
+import { purgeExpiredFileRefsWithBytes } from "../files/purge-expired-file-ref-bytes.js";
+import { FILE_REF_ENTITY_NAME } from "../files/types.js";
 import { SYSTEM_USER_ID } from "./system-user.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
@@ -77,9 +79,18 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
-        await deleteMany(db, proj.table, where);
+        await purgeExpiredRows(db, proj.source, proj.table, where, ctx);
     }
 };
+async function purgeExpiredRows(db, source, table, where, ctx) {
+    if (source === FILE_REF_ENTITY_NAME) {
+        // The row is the only record of the storageKey, so its bytes go first.
+        await purgeExpiredFileRefsWithBytes({ db, table, where, files: ctx.files, log: ctx.log });
+    }
+    else {
+        await deleteMany(db, table, where);
+    }
+}
 // System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
 // per-tenant grace period — there's no "this tenant's view" of a row that
 // isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace

package/dist/engine/types/index.d.ts

@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

package/dist/errors/classes.d.ts

@@ -60,6 +60,13 @@ export declare class PreconditionFailedError extends ConflictError {
     readonly code: string;
     constructor(details: PreconditionFailedDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
 }
+export declare class RecordLockedError extends ConflictError {
+    readonly code: string;
+    constructor(details: {
+        readonly entityName: string;
+        readonly entityId: number | string;
+    });
+}
 export declare class IdempotentReplayError extends ConflictError {
     readonly code: string;
     constructor(details: {

package/dist/errors/classes.js

@@ -119,6 +119,18 @@ export class PreconditionFailedError extends ConflictError {
         });
     }
 }
+// The entity's `lockedWhen` condition holds for the stored row: no write handler
+// may change or delete it. Same 409 family as the other state conflicts.
+export class RecordLockedError extends ConflictError {
+    code = "record_locked";
+    constructor(details) {
+        super({
+            message: `${details.entityName} ${details.entityId} is locked and cannot be changed`,
+            i18nKey: "errors.recordLocked",
+            details,
+        });
+    }
+}
 // The caller retried a write with an idempotencyKey it had already used —
 // the event-store's partial unique index on metadata.idempotencyKey caught
 // the duplicate. Distinct from unique_violation/version_conflict: this is

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export type { ErrorDocsConfig } from "./docs-url.js";
 export { resolveErrorDocsUrl } from "./docs-url.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";

package/dist/errors/index.js

@@ -1,4 +1,4 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { resolveErrorDocsUrl } from "./docs-url.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";

package/dist/files/assert-file-refs-belong-to-tenant.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export declare function assertFileRefsBelongToTenant(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<void>;

package/dist/files/assert-file-refs-belong-to-tenant.js

@@ -0,0 +1,50 @@
+import { isFileField, isUuid, } from "../engine/types/index.js";
+import { ValidationError } 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";
+// A file field only stores an id, and the file routes authorize by tenant at
+// read time: without this check a writer could name another tenant's fileRef
+// and make the record point at it. Only newly written values are checked (all
+// of a create, `changes` of an update), so existing data is left alone. The
+// error is the same for "missing" and "belongs to another tenant" so the id
+// cannot be probed across tenants.
+export async function assertFileRefsBelongToTenant(args) {
+    const { registry, result, user, db } = args;
+    // skip: saves of unregistered aggregates (custom executors) declare no file fields
+    if (result.entityName === undefined)
+        return;
+    const entity = registry.getEntity(result.entityName);
+    // skip: an aggregate without an entity definition has 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 executor = getFileRefExecutor();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
+            if (await isFileRefOfTenant(executor, fileRefId, user, db))
+                continue;
+            throw new ValidationError({
+                fields: [
+                    {
+                        path: fieldName,
+                        code: "invalid_element",
+                        i18nKey: "errors.validation.invalid_element",
+                    },
+                ],
+            });
+        }
+    }
+}
+async function isFileRefOfTenant(executor, fileRefId, user, db) {
+    if (!isUuid(fileRefId))
+        return false;
+    // detail() widens its tenant filter to (self, SYSTEM); only the writer's own
+    // tenant counts here, same as GET /files/:id/meta.
+    const row = await executor.detail({ id: fileRefId }, user, db);
+    return row !== null && row["tenantId"] === user.tenantId;
+}

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,5 +1,6 @@
 import type { TenantDb } from "../db/tenant-db.js";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;

package/dist/files/bind-pending-file-refs.js

@@ -2,7 +2,7 @@ import { isFileField, isUuid, } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
-function fileRefIdsOf(value) {
+export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];
     if (!Array.isArray(value))
@@ -15,16 +15,17 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
         row["fieldName"] === fieldName &&
         row["insertedById"] === user.id);
 }
-// A create form uploads before the record exists, so its fileRefs carry
-// entityType + fieldName but no entityId. Binding them in the create's own
-// transaction makes record-bound variants (qr overlay) and record-read file
-// access work for them. Only the caller's own pending uploads for exactly this
-// entity field are bound: naming someone else's upload id in a create payload
-// must not pull that file into a record the caller controls.
+// A form (or a server handler via createFileRefFromBytes) uploads before the
+// record references the file, so its fileRefs carry entityType + fieldName but
+// no entityId. Binding them in the save's own transaction makes record-bound
+// variants (qr overlay) and record-read file access work for them. Only the
+// caller's own pending uploads for exactly this entity field are bound: naming
+// someone else's upload id in a save payload must not pull that file into a
+// record the caller controls.
 export async function bindPendingFileRefs(args) {
     const { registry, result, user, db } = args;
-    // skip: only a create can carry still-pending uploads for its own record
-    if (!result.isNew || result.entityName === undefined)
+    // skip: saves of unnamed aggregates declare no file fields
+    if (result.entityName === undefined)
         return;
     const entityName = result.entityName;
     const entity = registry.getEntity(entityName);
@@ -38,10 +39,9 @@ export async function bindPendingFileRefs(args) {
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
-        // files/images fields have no projection column, so their ids are only in
-        // the create's input (changes), not in the returned row (data).
-        const namedIds = result.data[fieldName] ?? result.changes[fieldName];
-        for (const fileRefId of fileRefIdsOf(namedIds)) {
+        // changes, not data: an update's row carries every stored file id, including
+        // ones bound earlier; only the ids this save names can be pending uploads.
+        for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
             const row = await executor.detail({ id: fileRefId }, user, db);
             if (row === null || !isPendingUploadFor(row, entityName, fieldName, user))
                 continue;

package/dist/files/dispose-removed-file-refs.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export declare function disposeRemovedFileRefs(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<void>;

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/file-ref-entity.d.ts

@@ -1,4 +1,4 @@
-export declare const FILE_REF_ENTITY_NAME = "fileRef";
+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,7 +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 const FILE_REF_ENTITY_NAME = "fileRef";
+export { FILE_REF_ENTITY_NAME } from "./types.js";
 export const fileRefEntity = createEntity({
     table: "file_refs",
     softDelete: true,

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

@@ -3,6 +3,7 @@ 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;
@@ -29,6 +30,7 @@ export type FileRoutesOptions = {
     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

@@ -12,6 +12,7 @@ import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from
 import { createFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.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"];
@@ -22,16 +23,17 @@ const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
 // 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. Unattached files are tenant-wide (the tenant boundary is already
-// enforced by the query).
+// 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.entityType === null || fileRef.entityId === null)
-            return "allow";
         if (fileRef.insertedById === user.id)
             return "allow";
         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({
@@ -135,6 +137,28 @@ 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;
+        if (entityId !== undefined) {
+            if (entityType === undefined) {
+                return c.json({ error: "missing_entity_type: entityId requires entityType" }, 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);
+            }
+        }
         const data = new Uint8Array(await file.arrayBuffer());
         const storageProvider = await options.resolveProvider(user.tenantId);
         const outcome = await storeFileAsFileRef({

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-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 ?? [])