@cosmicdrift/kumiko-framework 0.359.0 → 0.361.0

package/dist/engine/feature-config-events-jobs.js

@@ -1,5 +1,6 @@
 import { escapeHatchGrantsProblem, normalizeEventPiiSubject, } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
+import { isValidIanaTimeZone } from "../time/iana.js";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
 import { QnTypes, qn, toKebab } from "./qualified-name.js";
@@ -168,6 +169,13 @@ export function buildConfigEventsJobsMethods(state, name) {
             if (jobGrantsProblem) {
                 throw new Error(`[Feature ${name}] r.job("${jobName}") declares an invalid escapeHatch — ${jobGrantsProblem}`);
             }
+            if ("cron" in jobOptions.trigger && jobOptions.trigger.tz !== undefined) {
+                const tz = jobOptions.trigger.tz;
+                if (!isValidIanaTimeZone(tz)) {
+                    throw new Error(`[Feature ${name}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(tz)} } — ` +
+                        'tz must be an IANA time zone name such as "Europe/Berlin".');
+                }
+            }
             // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
             // wird zu Array von resolved strings, Single bleibt single string —
             // job-runner unterscheidet anhand Array.isArray.

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/errors/reasons.d.ts

@@ -14,6 +14,7 @@ export declare const FrameworkReasons: {
     readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
     readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
     readonly subjectErased: "subject_erased";
+    readonly fileRejected: "file_rejected";
 };
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
 export declare const AgentReasons: {

package/dist/errors/reasons.js

@@ -66,6 +66,9 @@ export const FrameworkReasons = {
     // ConflictError: a write touched a personal-data field of a data subject whose
     // key was erased (crypto-shredding); the subject can no longer receive data.
     subjectErased: "subject_erased",
+    // UnprocessableError: createFileRefFromBytes refused the file (size, type,
+    // content or attach target). `details.error` carries the upload-route error string.
+    fileRejected: "file_rejected",
 };
 // Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
 // sister catalog to FrameworkReasons instead of extending it — see the

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

@@ -0,0 +1,9 @@
+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;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<void>;

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

@@ -0,0 +1,54 @@
+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";
+export function fileRefIdsOf(value) {
+    if (typeof value === "string")
+        return isUuid(value) ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && isUuid(item));
+}
+function isPendingUploadFor(row, entityName, fieldName, user) {
+    return (row["entityId"] === null &&
+        row["entityType"] === entityName &&
+        row["fieldName"] === fieldName &&
+        row["insertedById"] === user.id);
+}
+// 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: 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 executor = getFileRefExecutor();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        // 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;
+            const version = typeof row["version"] === "number" ? row["version"] : undefined;
+            const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);
+            if (!bound.isSuccess)
+                throw reraiseAsKumikoError(bound.error);
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import type { Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import { type CreatedFileRef } from "./create-file-ref.js";
+import type { FileContext } from "./file-handle.js";
+export type { CreatedFileRef };
+export type CreateFileRefContext = {
+    readonly db: TenantDb;
+    readonly files?: FileContext | undefined;
+    readonly registry: Registry;
+    readonly user: SessionUser;
+};
+export type CreateFileRefInput = {
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly data: Uint8Array;
+    readonly attachTo?: {
+        readonly entityType: string;
+        readonly fieldName: string;
+        readonly entityId?: string;
+    };
+};
+export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;

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

@@ -0,0 +1,39 @@
+import { FrameworkReasons, InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, } from "./create-file-ref.js";
+import { readFilesRouteOptions } from "./file-routes.js";
+// Server-side counterpart of POST /files for handlers/jobs that produce bytes
+// themselves (generated PDFs, exports). Same validation, storage layout and
+// fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
+export async function createFileRefFromBytes(ctx, input) {
+    const { files } = ctx;
+    if (!files) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromBytes: ctx.files is unavailable — mount a file-provider feature to store files",
+        }));
+    }
+    const outcome = await storeFileAsFileRef({
+        user: ctx.user,
+        tenantDb: ctx.db,
+        registry: ctx.registry,
+        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        writeBytes: (key, data, mimeType) => files.ref(key).write(data, mimeType),
+        deleteBytes: (key) => files.ref(key).delete(),
+    }, {
+        fileName: input.fileName,
+        declaredMimeType: input.mimeType,
+        data: input.data,
+        entityType: input.attachTo?.entityType,
+        entityId: input.attachTo?.entityId,
+        fieldName: input.attachTo?.fieldName,
+    });
+    switch (outcome.kind) {
+        case "created":
+            return { isSuccess: true, data: outcome.fileRef };
+        case "rejected":
+            return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, {
+                details: { error: outcome.error },
+            }));
+        case "failed":
+            return outcome.failure;
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.js";
+import type { WriteFailure } from "../errors/index.js";
+export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+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;
+    readonly data: Uint8Array;
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+};
+export type StoreFileDeps = {
+    readonly user: SessionUser;
+    readonly tenantDb: TenantDb;
+    readonly registry: Registry | undefined;
+    readonly defaultMaxUploadSize: string;
+    readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
+    readonly deleteBytes: (storageKey: string) => Promise<void>;
+};
+export type CreatedFileRef = {
+    readonly id: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly storageKey: string;
+};
+export type StoreFileOutcome = {
+    readonly kind: "created";
+    readonly fileRef: CreatedFileRef;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+} | {
+    readonly kind: "failed";
+    readonly failure: WriteFailure;
+};
+export declare function storeFileAsFileRef(deps: StoreFileDeps, input: StoreFileInput): Promise<StoreFileOutcome>;
+export {};

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

@@ -0,0 +1,135 @@
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { isFileField, } from "../engine/types/index.js";
+import { generateId } from "../utils/index.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";
+export const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+// Standard entity executor for fileRef: create/delete emit fileRef.created /
+// fileRef.deleted and write file_refs via applyEntityEvent in one tx
+// (read-your-own-write), exactly like any other entity's lifecycle. Built on
+// first use: the table builder's import graph reaches back into this module.
+let fileRefExecutor;
+function buildFileRefExecutor() {
+    return createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+        entityName: FILE_REF_ENTITY_NAME,
+    });
+}
+export function getFileRefExecutor() {
+    fileRefExecutor ??= buildFileRefExecutor();
+    return fileRefExecutor;
+}
+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 };
+}
+function acceptFile(deps, input) {
+    const { fileName, declaredMimeType, data, entityType, entityId, fieldName } = input;
+    const rejected = (error) => ({ kind: "rejected", error });
+    // These interpolate directly into the storage key (buildStorageKey) —
+    // reject anything but a safe identifier so a caller 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 && !SAFE_IDENTIFIER.test(value)) {
+            return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
+        }
+    }
+    let maxSize = deps.defaultMaxUploadSize;
+    let accept;
+    const attachedField = resolveAttachedField(deps.registry, entityType, fieldName);
+    if (attachedField.kind === "unresolvable") {
+        return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
+    }
+    if (attachedField.kind === "resolved") {
+        if (attachedField.fieldDef.maxSize)
+            maxSize = attachedField.fieldDef.maxSize;
+        if (attachedField.fieldDef.accept)
+            accept = attachedField.fieldDef.accept;
+    }
+    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
+    if (validationError)
+        return rejected(validationError);
+    const contentValidation = validateFileContent(fileName, data, accept);
+    if (contentValidation.kind === "rejected")
+        return rejected(contentValidation.error);
+    // 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.
+    if (contentValidation.kind === "normalized") {
+        return {
+            kind: "accepted",
+            mimeType: contentValidation.mimeType,
+            extension: contentValidation.extension,
+        };
+    }
+    const mimeTypeResolution = resolveUploadMimeType(fileName, declaredMimeType, data);
+    if (mimeTypeResolution.kind === "rejected")
+        return rejected(mimeTypeResolution.error);
+    return {
+        kind: "accepted",
+        mimeType: resolveContentType({
+            declared: mimeTypeResolution.mimeType,
+            bytes: data,
+            filename: fileName,
+        }),
+        extension: undefined,
+    };
+}
+// The one upload pipeline behind POST /files and createFileRefFromBytes.
+export async function storeFileAsFileRef(deps, input) {
+    const { fileName, data, entityType, entityId, fieldName } = input;
+    const accepted = acceptFile(deps, input);
+    if (accepted.kind === "rejected")
+        return accepted;
+    const { mimeType, extension } = accepted;
+    const fileRefId = generateId();
+    const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
+    // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
+    // inside a PG connection's tx window). A failed create deletes the bytes
+    // again below; a later rollback of an enclosing transaction cannot, so
+    // those are orphaned for the cleanup-jobs to sweep. Losing a row on
+    // append-failure is acceptable; a committed row with a missing binary is not.
+    await deps.writeBytes(storageKey, data, mimeType);
+    // id is explicit so the response + storageKey stay consistent; tenantId,
+    // insertedAt and insertedById are set by applyEntityEvent from the event metadata.
+    const result = await getFileRefExecutor().create({
+        id: fileRefId,
+        storageKey,
+        fileName,
+        mimeType,
+        size: data.byteLength,
+        entityType: entityType ?? null,
+        entityId: entityId ?? null,
+        fieldName: fieldName ?? null,
+    }, deps.user, deps.tenantDb);
+    if (!result.isSuccess) {
+        try {
+            await deps.deleteBytes(storageKey);
+        }
+        catch {
+            // skip: the create failure is the error worth reporting; leftover bytes are swept by cleanup-jobs.
+        }
+        return { kind: "failed", failure: result };
+    }
+    return {
+        kind: "created",
+        fileRef: { id: fileRefId, fileName, mimeType, size: data.byteLength, storageKey },
+    };
+}

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>;