@cosmicdrift/kumiko-framework 0.360.0 → 0.362.0

package/dist/engine/boot-validator/screens.js

@@ -32,6 +32,44 @@ function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions
 // literal `required: true` (screen-spec override or entity-level default).
 // A dynamic FieldCondition depends on runtime form values and can't be
 // evaluated at boot; buildFormSchema() silently skips presence-checking it.
+// `embeddedList` and `prefill` only make sense on field types that support them;
+// a misplaced spec would otherwise be a silent no-op.
+function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
+    const fieldDef = entityDef.fields[fieldSpec.field];
+    // skip: the field name is not on the entity, other checks report unknown fields
+    if (fieldDef === undefined)
+        return;
+    const where = `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${fieldSpec.field}"`;
+    const listSpec = fieldSpec.embeddedList;
+    if (listSpec !== undefined) {
+        if (fieldDef.type !== "embedded" || fieldDef.multiple !== true) {
+            throw new Error(`${where} sets embeddedList, which only applies to an embedded list ` +
+                `(createEmbeddedListField); the field is type "${fieldDef.type}".`);
+        }
+        for (const cell of listSpec.readOnlyCells ?? []) {
+            if (fieldDef.schema[cell] === undefined) {
+                throw new Error(`${where} embeddedList.readOnlyCells names "${cell}", which is not a sub-field ` +
+                    `(known: ${Object.keys(fieldDef.schema).sort().join(", ")}).`);
+            }
+        }
+    }
+    const prefill = fieldSpec.prefill;
+    // skip: no prefill declared
+    if (prefill === undefined)
+        return;
+    if (prefill.kind === "today") {
+        if (fieldDef.type !== "date") {
+            throw new Error(`${where} prefill "today" needs a date field; the field is type "${fieldDef.type}".`);
+        }
+        // skip: today carries no property, nothing further to check
+        return;
+    }
+    const allowsUserId = fieldDef.type === "text" || fieldDef.type === "reference";
+    if (prefill.property === "id" ? !allowsUserId : fieldDef.type !== "text") {
+        throw new Error(`${where} prefill currentUser.${prefill.property} does not fit a field of type ` +
+            `"${fieldDef.type}" (displayName and email need text; id needs text or a reference).`);
+    }
+}
 function validateNoWidgetRequiredField(featureName, screenId, entityDef, fieldSpec) {
     const fieldDef = entityDef.fields[fieldSpec.field];
     // skip: field doesn't exist or its type already has a widget — nothing to validate.
@@ -648,7 +686,8 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
 // form (fw#2670) carries the same target under `screen` plus the payload
 // field `idFrom`. Shared by actionForm/secretMint (validateInlineFormNavTargets)
 // and entityEdit — same rule, same error message, one place to keep them in sync.
-function validateRedirectTarget(feature, screenId, screenKind, redirect, allScreenQns) {
+function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups) {
+    const { allScreenQns } = lookups;
     const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
     if (typeof redirect !== "string" &&
         (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")) {
@@ -674,6 +713,13 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, allScre
         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is set but target screen ` +
             `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`);
     }
+    if (typeof redirect !== "string" && redirect.tab !== undefined) {
+        const targetQn = resolveScreenTargetQn(feature.name, redirectTarget);
+        const target = lookups.screensByShortId
+            .get(targetQn.slice(targetQn.lastIndexOf(":") + 1))
+            ?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === targetQn);
+        validateRowActionNavigateTab(feature.name, screenId, screenKind, "redirect", { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, target);
+    }
 }
 // redirect is only honored on record actions; on list/related-list row
 // actions it would be silently dropped, so the author would believe it works.
@@ -686,9 +732,25 @@ function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action
 }
 // A writeHandler record action's redirect (projectionDetail/entityEdit
 // header and section actions) follows the entityEdit.redirect rule.
-function validateRecordActionRedirect(feature, screenId, screenKind, action, allScreenQns) {
+function validateRecordActionRedirect(feature, screenId, screenKind, action, lookups) {
     if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
-        validateRedirectTarget(feature, screenId, screenKind, action.redirect, allScreenQns);
+        validateRedirectTarget(feature, screenId, screenKind, action.redirect, lookups);
+    }
+}
+// "edit" is the default edit action, which only exists when detailFor names
+// the entity; a typo would otherwise silently fall back to the default precedence.
+function validatePrimaryActionTarget(featureName, screenId, screen) {
+    // skip: no declared primaryAction, the default header precedence applies
+    if (screen.primaryAction === undefined)
+        return;
+    const declaredIds = (screen.actions ?? []).map((action) => action.id);
+    const editIsAvailable = screen.detailFor !== undefined;
+    const targetExists = declaredIds.includes(screen.primaryAction) ||
+        (editIsAvailable && screen.primaryAction === "edit");
+    if (!targetExists) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) primaryAction "${screen.primaryAction}" ` +
+            `matches no action — use one of the declared action ids (${declaredIds.join(", ") || "none declared"})` +
+            `${editIsAvailable ? ' or "edit"' : ' ("edit" needs detailFor on this screen)'}.`);
     }
 }
 function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap) {
@@ -718,9 +780,10 @@ function validateScreenFallback(feature, screenId, screenType, fallback, allScre
         throw new Error(`${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`);
     }
 }
-function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns) {
+function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups) {
+    const { allScreenQns } = lookups;
     if (screen.redirect !== undefined) {
-        validateRedirectTarget(feature, screenId, kind, screen.redirect, allScreenQns);
+        validateRedirectTarget(feature, screenId, kind, screen.redirect, lookups);
     }
     if (typeof screen.cancelTarget === "string") {
         // Same rule as redirect — `false` (no Cancel button) needs no validation.
@@ -729,7 +792,7 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreen
 }
 // actionForm/secretMint have no entity link, only a write-handler QN +
 // inline fields: checks handler registration, field types, layout refs, and nav targets.
-function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, allScreenQns, featureMap) {
+function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, lookups, featureMap) {
     validateWriteHandlerRegistered(feature.name, screenId, kind, screen.handler, allWriteHandlerQns);
     // Only a secretMint's own mint step may skip fields/sections entirely
     // (input-less mint, fw#2838) — actionForm always needs at least one field.
@@ -737,7 +800,7 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
     validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, allowEmptyMintForm && fieldNames.size === 0);
     validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
-    validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns);
+    validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
 // on the reveal card in place of the bare acknowledge button (TOTP enrollment:
@@ -965,6 +1028,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
     };
     for (const [screenId, screen] of Object.entries(feature.screens)) {
         validateExplicitListScreenExists(feature.name, screenId, screen, screensByShortId);
+        if ((screen.type === "entityList" || screen.type === "projectionList") &&
+            screen.emptyState?.action !== undefined) {
+            validateActionHasIcon(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action);
+            validateNavigateActionTab(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action, navigateLookups);
+        }
         // Output of buildAppSchema, which overwrites it — an authored value would be a silent no-op.
         if ((screen.type === "entityEdit" ||
             screen.type === "actionForm" ||
@@ -1169,7 +1237,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 if (section.actions !== undefined) {
                     for (const action of section.actions) {
                         validateActionHasIcon(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" action`, action);
-                        validateRecordActionRedirect(feature, screenId, "projectionDetail", action, allScreenQns);
+                        validateRecordActionRedirect(feature, screenId, "projectionDetail", action, navigateLookups);
                         validateNavigateActionTab(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" action`, action, navigateLookups);
                     }
                 }
@@ -1277,10 +1345,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // the row), so the same navigate/writeHandler existence checks as
             // entityList/projectionList apply. `rowClick` is rejected outright —
             // a detail screen has no row to click.
+            validatePrimaryActionTarget(feature.name, screenId, screen);
             if (screen.actions !== undefined) {
                 for (const action of screen.actions) {
                     validateActionHasIcon(feature.name, screenId, "projectionDetail", "action", action);
-                    validateRecordActionRedirect(feature, screenId, "projectionDetail", action, allScreenQns);
+                    validateRecordActionRedirect(feature, screenId, "projectionDetail", action, navigateLookups);
                     if (action.kind === "navigate" && action.rowClick === true) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(projectionDetail) action "${action.id}" sets rowClick: true — there is no row to ` +
@@ -1381,11 +1450,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             continue;
         }
         if (screen.type === "actionForm") {
-            validateInlineFormScreen(feature, screenId, screen, "actionForm", allWriteHandlerQns, allScreenQns, featureMap);
+            validateInlineFormScreen(feature, screenId, screen, "actionForm", allWriteHandlerQns, navigateLookups, featureMap);
             continue;
         }
         if (screen.type === "secretMint") {
-            validateInlineFormScreen(feature, screenId, screen, "secretMint", allWriteHandlerQns, allScreenQns, featureMap);
+            validateInlineFormScreen(feature, screenId, screen, "secretMint", allWriteHandlerQns, navigateLookups, featureMap);
             if (screen.reveal.fields.length === 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (secretMint) has an empty reveal.fields ` +
                     `list — declare at least one field to reveal.`);
@@ -1663,7 +1732,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     const sectionLabel = section.title ?? section.id ?? "(untitled)";
                     for (const action of section.actions) {
                         validateActionHasIcon(feature.name, screenId, "entityEdit", `section "${sectionLabel}" action`, action);
-                        validateRecordActionRedirect(feature, screenId, "entityEdit", action, allScreenQns);
+                        validateRecordActionRedirect(feature, screenId, "entityEdit", action, navigateLookups);
                         validateNavigateActionTab(feature.name, screenId, "entityEdit", `section "${sectionLabel}" action`, action, navigateLookups);
                     }
                 }
@@ -1690,6 +1759,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         throw new Error(buildUnknownFieldMessage(feature.name, screenId, normalized.field, screen.entity, fieldNames));
                     }
                     validateNoWidgetRequiredField(feature.name, screenId, entityDef, normalized);
+                    validateEditFieldExtras(feature.name, screenId, entityDef, normalized);
                 }
             }
             validateWizardLayout(feature.name, screenId, "entityEdit", screen.layout, featureMap);
@@ -1699,7 +1769,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // row to click either.
             if (screen.actions !== undefined) {
                 for (const action of screen.actions) {
-                    validateRecordActionRedirect(feature, screenId, "entityEdit", action, allScreenQns);
+                    validateRecordActionRedirect(feature, screenId, "entityEdit", action, navigateLookups);
                     if (action.kind === "navigate" && action.rowClick === true) {
                         throw new Error(`[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
                             `(entityEdit) action "${action.id}" sets rowClick: true — there is no row to click ` +
@@ -1726,8 +1796,13 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     `"${screen.recordTitleField}" is not a field of entity "${screen.entity}" ` +
                     `(known: ${[...fieldNames].sort().join(", ")}).`);
             }
+            if (typeof screen.readOnly === "object" && !fieldNames.has(screen.readOnly.field)) {
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) readOnly condition field ` +
+                    `"${screen.readOnly.field}" is not a field of entity "${screen.entity}" ` +
+                    `(known: ${[...fieldNames].sort().join(", ")}).`);
+            }
             if (screen.redirect !== undefined) {
-                validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, allScreenQns);
+                validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, navigateLookups);
             }
         }
     }

package/dist/engine/build-app-schema.js

@@ -409,6 +409,7 @@ function projectEntity(entityName, entity) {
         ...(typeof entity.defaultCurrency === "string" && {
             defaultCurrency: entity.defaultCurrency,
         }),
+        ...(entity.lockedWhen !== undefined && { lockedWhen: entity.lockedWhen }),
     };
 }
 // Nur valueType durch — die derive-fn ist Server-only und NICHT JSON-safe

package/dist/engine/define-handler.js

@@ -46,9 +46,7 @@ export function defineWriteHandler(def,
         ...(def.access && { access: def.access }),
         ...(def.description !== undefined && { description: def.description }),
         ...(def.agent && { agent: def.agent }),
-        ...(def.unsafeSkipTransitionGuard && {
-            unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
-        }),
+        ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),

package/dist/engine/factories.d.ts

@@ -184,6 +184,8 @@ export declare function createEntity<F, const T extends EntityTenancy = "tenant"
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;
     readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    /** See EntityDefinition.lockedWhen. */
+    readonly lockedWhen?: EntityDefinition["lockedWhen"];
     readonly indexes?: readonly EntityIndexDef[];
     readonly idType?: "serial" | "uuid";
     readonly access?: EntityDefinition["access"];

package/dist/engine/feature-ast/extractors/round3.d.ts

@@ -2,7 +2,7 @@ import type { CallExpression, SourceFile } from "ts-morph";
 import type { ClaimKeyType } from "../../types/handlers.js";
 import type { ParseError } from "../parse.js";
 import type { ClaimKeyPattern, ConfigPattern, MetricPattern, ReferenceDataPattern, SecretNamespacePattern, SecretPattern, TranslationsPattern, UseExtensionPattern } from "../patterns.js";
-import { type ExtractOutput } from "./shared.js";
+import { type ExtractOutput, type ReadDataLiteralOptions } from "./shared.js";
 export type NamedOptionsResult = {
     readonly kind: "ok";
     readonly name: string;
@@ -11,7 +11,7 @@ export type NamedOptionsResult = {
     readonly kind: "error";
     readonly error: ParseError;
 };
-export declare function readNamedOptions(call: CallExpression, sourceFile: SourceFile, methodName: string): NamedOptionsResult;
+export declare function readNamedOptions(call: CallExpression, sourceFile: SourceFile, methodName: string, readOptions?: ReadDataLiteralOptions): NamedOptionsResult;
 export declare function extractConfig(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ConfigPattern>;
 export declare function extractTranslations(call: CallExpression, sourceFile: SourceFile): ExtractOutput<TranslationsPattern>;
 export declare function extractMetric(call: CallExpression, sourceFile: SourceFile): ExtractOutput<MetricPattern>;

package/dist/engine/feature-ast/extractors/round3.js

@@ -1,7 +1,7 @@
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
 import { fail, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameLiteralRef, readNameOrRef, } from "./shared.js";
-export function readNamedOptions(call, sourceFile, methodName) {
+export function readNamedOptions(call, sourceFile, methodName, readOptions = {}) {
     const args = call.getArguments();
     const first = args[0];
     if (!first) {
@@ -17,7 +17,7 @@ export function readNamedOptions(call, sourceFile, methodName) {
         if (!nameInit) {
             return fail(methodName, sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const data = readDataLiteralNode(obj);
+        const data = readDataLiteralNode(obj, readOptions);
         if (!isPlainObject(data)) {
             return fail(methodName, sourceLocationFromNode(call, sourceFile), "argument could not be read as a plain object");
         }
@@ -32,7 +32,7 @@ export function readNamedOptions(call, sourceFile, methodName) {
     if (!optionsArg) {
         return fail(methodName, sourceLocationFromNode(call, sourceFile), "expected an options object as second argument");
     }
-    const options = readDataLiteralNode(optionsArg);
+    const options = readDataLiteralNode(optionsArg, readOptions);
     if (!isPlainObject(options)) {
         return fail(methodName, sourceLocationFromNode(call, sourceFile), "options could not be read as a plain object");
     }
@@ -88,7 +88,7 @@ export function extractMetric(call, sourceFile) {
     });
 }
 export function extractSecret(call, sourceFile) {
-    const parsed = readNamedOptions(call, sourceFile, "secret");
+    const parsed = readNamedOptions(call, sourceFile, "secret", { functionValuesAsRaw: true });
     if (parsed.kind === "error")
         return parsed;
     return ok({

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/bind-referenced-files.write.d.ts

@@ -0,0 +1,16 @@
+import * as z from "zod";
+export type BindReferencedFilesResult = {
+    readonly bound: number;
+    readonly skipped: number;
+    readonly nextAfterId: string | null;
+};
+export declare const bindReferencedFilesWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"bindReferencedFiles", z.ZodObject<{
+    entityType: z.ZodString;
+    entityIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+    afterId: z.ZodOptional<z.ZodUUID>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, {
+    bound: number;
+    skipped: number;
+    nextAfterId: string | null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;