@cosmicdrift/kumiko-framework 0.399.0 → 0.400.0

package/dist/engine/field-state.js

@@ -0,0 +1,67 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { evalFieldCondition, isUnchangedValue } from "./screen-helpers.js";
+export function isMissingRequiredValue(value) {
+    return (value === undefined ||
+        value === null ||
+        value === "" ||
+        (Array.isArray(value) && value.length === 0));
+}
+export function isFieldVisible(def, values) {
+    return def.visibleWhen === undefined || evalFieldCondition(def.visibleWhen, values);
+}
+export function isFieldRequired(def, values) {
+    if (!isFieldVisible(def, values))
+        return false;
+    return (def.required === true ||
+        (def.requiredWhen !== undefined && evalFieldCondition(def.requiredWhen, values)));
+}
+function watchedKeys(name, def) {
+    return [
+        name,
+        ...(def.requiredWhen ? [def.requiredWhen.field] : []),
+        ...(def.visibleWhen ? [def.visibleWhen.field] : []),
+    ];
+}
+function embeddedRowsOf(def, value) {
+    if (def.multiple === true)
+        return Array.isArray(value) ? value.map((row, index) => ({ row, index })) : [];
+    return isPlainObject(value) ? [{ row: value, index: undefined }] : [];
+}
+function findMissingEmbeddedRequirements(name, def, value) {
+    const missing = [];
+    for (const { row, index } of embeddedRowsOf(def, value)) {
+        if (!isPlainObject(row))
+            continue;
+        for (const [subName, sub] of Object.entries(def.schema)) {
+            if (sub.requiredWhen === undefined)
+                continue;
+            if (!isFieldRequired(sub, row) || !isMissingRequiredValue(row[subName]))
+                continue;
+            missing.push(index === undefined ? `${name}.${subName}` : `${name}.${index}.${subName}`);
+        }
+    }
+    return missing;
+}
+/** Paths of fields (and embedded sub-fields) whose `requiredWhen` holds while the value is missing.
+ *  With `previous`, a field is only checked when it or one of its condition fields changed, so
+ *  legacy rows stay editable. */
+export function findMissingConditionalRequirements(fields, values, previous) {
+    const missing = [];
+    for (const [name, def] of Object.entries(fields)) {
+        if (!isFieldVisible(def, values))
+            continue;
+        if (def.requiredWhen !== undefined) {
+            const unchanged = previous !== undefined &&
+                watchedKeys(name, def).every((key) => isUnchangedValue(values[key], previous[key]));
+            if (!unchanged && isFieldRequired(def, values) && isMissingRequiredValue(values[name])) {
+                missing.push(name);
+            }
+        }
+        if (def.type !== "embedded")
+            continue;
+        if (previous !== undefined && isUnchangedValue(values[name], previous[name]))
+            continue;
+        missing.push(...findMissingEmbeddedRequirements(name, def, values[name]));
+    }
+    return missing;
+}

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

@@ -11,6 +11,9 @@ import type { NameOrRef, WriteResult } from "./types/handlers.ts";
  * return withResponseData(result, { userId, tenantId });
  * ```
  *
+ * When the executor result is a save/delete, it rides along as `lifecycle`, so postSave/postDelete
+ * hooks and projections still run; the dispatcher keeps it out of the response.
+ *
  * On failure the same WriteFailure instance is returned — the error
  * object round-trips without any wrapping, so the dispatcher / HTTP layer
  * still read the original error code + httpStatus + i18nKey.

package/dist/engine/handler-helpers.js

@@ -1,3 +1,4 @@
+import { isLifecycleResult } from "../pipeline/dispatcher-utils.js";
 /**
  * Override the success-side `data` of a WriteResult while forwarding the
  * failure half untouched. Useful for handlers that delegate to the
@@ -10,6 +11,9 @@
  * return withResponseData(result, { userId, tenantId });
  * ```
  *
+ * When the executor result is a save/delete, it rides along as `lifecycle`, so postSave/postDelete
+ * hooks and projections still run; the dispatcher keeps it out of the response.
+ *
  * On failure the same WriteFailure instance is returned — the error
  * object round-trips without any wrapping, so the dispatcher / HTTP layer
  * still read the original error code + httpStatus + i18nKey.
@@ -17,7 +21,9 @@
 export function withResponseData(result, data) {
     if (!result.isSuccess)
         return result;
-    return { isSuccess: true, data };
+    return isLifecycleResult(result.data)
+        ? { isSuccess: true, data, lifecycle: result.data }
+        : { isSuccess: true, data };
 }
 export function resolveName(ref) {
     return typeof ref === "string" ? ref : ref.name;

package/dist/engine/index.d.ts

@@ -45,7 +45,7 @@ export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow.
 export type { ToggleReader } from "./effective-features.ts";
 export { computeEffectiveFeatures, isToggleableFeature } from "./effective-features.ts";
 export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, } from "./entity-handlers.ts";
-export { referenceGroupLabels } from "./entity-list-runtime-options.ts";
+export { parentVisibilityFor, referenceGroupLabels } from "./entity-list-runtime-options.ts";
 export { declareEscapeHatch } from "./escape-hatch-declaration.ts";
 export { CODEMOD_PLACEHOLDER_REASON_MARKER } from "./escape-hatch-reason.ts";
 export { emitEvent, typedPayload } from "./event-helpers.ts";
@@ -68,7 +68,7 @@ export { HookPhases } from "./hook-helpers.ts";
 export { i18nKey } from "./i18n-key.ts";
 export { buildSessionRoles, findForbiddenMembershipRole, } from "./membership-roles.ts";
 export type { OwnershipMap } from "./ownership.ts";
-export { from, normalizeAccessEntry, } from "./ownership.ts";
+export { from, normalizeAccessEntry, userCanWriteFieldRow, } from "./ownership.ts";
 export { pagedListSchema, pageRows, } from "./paged-list.ts";
 export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target.ts";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline.ts";

package/dist/engine/index.js

@@ -27,7 +27,7 @@ export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHand
 // apps use the verb-specific wrappers above. Existing callers (integration
 // tests, old bundled-features) remain runnable without changes.
 defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, } from "./entity-handlers.js";
-export { referenceGroupLabels } from "./entity-list-runtime-options.js";
+export { parentVisibilityFor, referenceGroupLabels } from "./entity-list-runtime-options.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export { CODEMOD_PLACEHOLDER_REASON_MARKER } from "./escape-hatch-reason.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
@@ -52,7 +52,7 @@ export { i18nKey } from "./i18n-key.js";
 // representation a semver promise; the predicate functions are the intended
 // surface.
 export { buildSessionRoles, findForbiddenMembershipRole, } from "./membership-roles.js";
-export { from, normalizeAccessEntry, } from "./ownership.js";
+export { from, normalizeAccessEntry, userCanWriteFieldRow, } from "./ownership.js";
 export { pagedListSchema, pageRows, } from "./paged-list.js";
 export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target.js";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline.js";

package/dist/engine/ownership.d.ts

@@ -9,5 +9,5 @@ export declare function normalizeAccessEntry(entry: OwnershipMap | readonly stri
 export declare function userCanCreateFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, newRow: Readonly<Record<string, unknown>>): boolean;
 export declare function tableNameOf(table: unknown): string;
 export declare function shiftParams(fragment: SqlFragment, shift: number): SqlFragment;
-export declare function buildOwnershipClause(user: SessionUser, accessMap: OwnershipMap | undefined, table: unknown, paramStart?: number): OwnershipClause;
+export declare function buildOwnershipClause(user: SessionUser, accessMap: OwnershipMap | undefined, table: unknown, paramStart?: number, tableNameOverride?: string): OwnershipClause;
 export declare function combineClauses(a: OwnershipClause, b: OwnershipClause): OwnershipClause;

package/dist/engine/ownership.js

@@ -229,7 +229,10 @@ export function shiftParams(fragment, shift) {
 //      does this outside `buildOwnershipClause`) — this function does not.
 //   3. Treat `kind: "empty"` (see `OwnershipClause`) as a hard DENY, and
 //      `kind: "pass"` as an explicit bypass — not as "no additional filter".
-export function buildOwnershipClause(user, accessMap, table, paramStart = 1) {
+//
+// `tableNameOverride` is the alias the queried table carries in the caller's SQL: where-rules
+// qualify columns with it, and a physical name would bind to an outer row of the same table.
+export function buildOwnershipClause(user, accessMap, table, paramStart = 1, tableNameOverride) {
     if (!accessMap || Object.keys(accessMap).length === 0)
         return PASS_CLAUSE;
     const clauses = [];
@@ -243,7 +246,7 @@ export function buildOwnershipClause(user, accessMap, table, paramStart = 1) {
         anyRoleMatched = true;
         if (rule === "all")
             return PASS_CLAUSE;
-        const resolved = ruleToFragment(rule, user, table, nextParamIdx);
+        const resolved = ruleToFragment(rule, user, table, nextParamIdx, tableNameOverride);
         if (resolved.kind === "sql") {
             clauses.push({ sqlText: resolved.sqlText, params: resolved.params });
             nextParamIdx += resolved.params.length;
@@ -297,20 +300,21 @@ function cachedTableColumnSqlNames(table) {
     }
     return names;
 }
-function ruleToFragment(rule, user, table, paramStart) {
+function ruleToFragment(rule, user, table, paramStart, tableNameOverride) {
     if (rule === "all") {
         return { kind: "sql", sqlText: "TRUE", params: [] };
     }
     if (rule.kind === "where") {
+        const tableName = tableNameOverride ?? tableNameOf(table);
         const frag = rule.where(user, {
             table,
-            tableName: tableNameOf(table),
+            tableName,
             paramStart,
         });
         // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
         // an unqualified column in a correlated subquery silently turns into a
         // fail-open tautology — throw instead of shipping it.
-        assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
+        assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableName}"`);
         return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
     }
     // FromRule

package/dist/engine/registry-state.d.ts

@@ -22,6 +22,7 @@ export type SearchableReferenceField = {
     readonly labelField: string;
 };
 export type SortableReferenceField = SearchableReferenceField;
+export declare const IMPLICIT_PROJECTION_SUFFIX: "-entity";
 export declare function buildImplicitProjection(featureName: string, entityName: string, entity: EntityDefinition, qualify: typeof qualifyEntityName, backingTable?: unknown, extensions?: readonly EntityProjectionExtension[]): ProjectionDefinition;
 export declare const qualify: typeof qualifyEntityName;
 export type RegistryState = {

package/dist/engine/registry-state.js

@@ -4,7 +4,7 @@ import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
 import { asEntityTableMeta } from "../db/query.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { qualifyEntityName } from "./qualified-name.js";
-const IMPLICIT_PROJECTION_SUFFIX = "-entity";
+export const IMPLICIT_PROJECTION_SUFFIX = "-entity";
 // Each `r.entity` registration gets an implicit projection with generated
 // apply handlers for the four automatic verbs. The live path writes directly
 // to the table through EventStoreExecutor, while rebuildProjection replays

package/dist/engine/schema-builder.js

@@ -73,6 +73,9 @@ function embeddedSubFieldToZod(subField) {
         }
         case "reference":
             return z.uuid();
+        case "images":
+        case "files":
+            return fileListFieldToZod(subField);
         default:
             assertUnreachable(subField, "embedded sub-field type");
     }

package/dist/engine/strip-unreadable-related-lists.d.ts

@@ -0,0 +1,4 @@
+import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
+import type { AppSchema } from "../ui-types/app-schema.ts";
+export type QueryAccessLookup = (queryQn: string) => AccessRule | undefined;
+export declare function stripUnreadableRelatedLists(schema: AppSchema, roles: readonly string[], queryAccess: QueryAccessLookup): AppSchema;

package/dist/engine/strip-unreadable-related-lists.js

@@ -0,0 +1,80 @@
+import { hasAccess } from "./access.js";
+// A relatedList section runs its own query; a caller whose roles cannot execute that query would
+// see a tab that only ever errors, so the section is removed from the role's schema.
+export function stripUnreadableRelatedLists(schema, roles, queryAccess) {
+    const canRun = (queryQn) => hasAccess({ roles }, queryAccess(queryQn));
+    let changed = false;
+    const features = schema.features.map((feature) => {
+        const next = stripFeature(feature, canRun);
+        if (next !== feature)
+            changed = true;
+        return next;
+    });
+    return changed ? { ...schema, features } : schema;
+}
+function stripFeature(feature, canRun) {
+    let changed = false;
+    const screens = feature.screens.map((screen) => {
+        const next = stripScreen(screen, canRun);
+        if (next !== screen)
+            changed = true;
+        return next;
+    });
+    return changed ? { ...feature, screens } : feature;
+}
+function stripScreen(screen, canRun) {
+    switch (screen.type) {
+        case "projectionDetail":
+            return stripProjectionDetail(screen, canRun);
+        case "entityEdit":
+            return stripEntityEdit(screen, canRun);
+        case "entityList":
+            return stripExpandableRow(screen, canRun);
+        default:
+            return screen;
+    }
+}
+function stripExpandableRow(screen, canRun) {
+    if (screen.expandableRow === undefined || canRun(screen.expandableRow.query))
+        return screen;
+    const { expandableRow: _removed, ...rest } = screen;
+    return rest;
+}
+function stripEntityEdit(screen, canRun) {
+    const { layout } = stripLayout(screen.layout, canRun);
+    return layout === screen.layout ? screen : { ...screen, layout };
+}
+function stripProjectionDetail(screen, canRun) {
+    const { layout, removedIds } = stripLayout(screen.layout, canRun);
+    if (layout === screen.layout)
+        return screen;
+    const metrics = screen.metrics?.map((metric) => stripDeadTabNavigate(metric, removedIds));
+    return { ...screen, layout, ...(metrics !== undefined && { metrics }) };
+}
+function stripLayout(layout, canRun) {
+    const removedIds = [];
+    const sections = layout.sections.filter((section) => {
+        if (!isUnrunnableRelatedList(section, canRun))
+            return true;
+        if (section.id !== undefined)
+            removedIds.push(section.id);
+        return false;
+    });
+    if (sections.length === layout.sections.length)
+        return { layout, removedIds };
+    return { layout: { ...layout, sections }, removedIds };
+}
+function isUnrunnableRelatedList(section, canRun) {
+    return section.kind === "relatedList" && !canRun(section.query);
+}
+function stripDeadTabNavigate(metric, removedTabIds) {
+    const navigate = metric.navigate;
+    const pointsAtRemovedTab = navigate?.tab !== undefined &&
+        navigate.screen === undefined &&
+        navigate.entity === undefined &&
+        removedTabIds.includes(navigate.tab);
+    if (!pointsAtRemovedTab)
+        return metric;
+    const { navigate: _removed, ...rest } = metric;
+    return rest;
+}

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

@@ -1,6 +1,6 @@
-import { isFileField } from "../engine/field-helpers.js";
 import { ValidationError } from "../errors/index.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { assertRowFitsFileField } from "./bind-pending-file-refs.js";
+import { fileRefIdsBySubField, fileRefIdsInField, holdsFileRefs, resolveFileSubField, } from "./file-field-slots.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
@@ -23,6 +23,24 @@ function isBoundToOtherRecord(row, entityName, recordId) {
         return false;
     return row["entityType"] !== entityName || boundId !== recordId;
 }
+// A file sub-field may be stricter than the sibling the upload came in through (`images` next
+// to `files`); the upload was only checked against the sub-field it named. Ids a sub-field
+// already held are not re-checked, a move from another sub-field counts as new.
+function assertNewIdsFitSubFields(fieldDef, previous, changes, fileRefRows) {
+    const previousBySubField = fileRefIdsBySubField(fieldDef, previous);
+    for (const [subField, ids] of fileRefIdsBySubField(fieldDef, changes)) {
+        const subFieldDef = resolveFileSubField(fieldDef, subField);
+        if (subFieldDef === undefined)
+            continue;
+        for (const fileRefId of ids) {
+            if (previousBySubField.get(subField)?.includes(fileRefId))
+                continue;
+            const row = fileRefRows.get(fileRefId);
+            if (row !== undefined)
+                assertRowFitsFileField(row, subFieldDef);
+        }
+    }
+}
 export function assertFileRefsBelongToTenant(args) {
     const { registry, result, fileRefRows } = args;
     // skip: saves of unregistered aggregates (custom executors) declare no file fields
@@ -38,15 +56,16 @@ export function assertFileRefsBelongToTenant(args) {
     const recordId = String(result.id);
     const alreadyHeld = new Set();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef))
+        if (!holdsFileRefs(fieldDef))
             continue;
-        for (const fileRefId of fileRefIdsOf(result.previous[fieldName]))
+        for (const fileRefId of fileRefIdsInField(fieldDef, result.previous[fieldName])) {
             alreadyHeld.add(fileRefId);
+        }
     }
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef))
+        if (!holdsFileRefs(fieldDef))
             continue;
-        for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
+        for (const fileRefId of fileRefIdsInField(fieldDef, result.changes[fieldName])) {
             // A value the record already holds is no new binding; its file_refs row may be gone
             // (forget purged the file), and sending the unchanged field back must still save.
             if (alreadyHeld.has(fileRefId))
@@ -64,5 +83,6 @@ export function assertFileRefsBelongToTenant(args) {
                 ],
             });
         }
+        assertNewIdsFitSubFields(fieldDef, result.previous[fieldName], result.changes[fieldName], fileRefRows);
     }
 }

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

@@ -1,8 +1,9 @@
+import type { AnyFileFieldDef } from "@cosmicdrift/kumiko-types/fields";
 import type { SaveContext } from "@cosmicdrift/kumiko-types/hooks";
 import type { TenantDb } from "../db/tenant-db.ts";
 import type { Registry, SessionUser } from "../engine/types/index.ts";
 import { type FileRefRows } from "./load-save-file-refs.ts";
-export declare function fileRefIdsOf(value: unknown): readonly string[];
+export { fileRefIdsOf } from "./file-field-slots.ts";
 type FileRefRow = Readonly<Record<string, unknown>>;
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
@@ -31,6 +32,7 @@ export type PendingFileRefBindTarget = {
     readonly fieldName: string;
 };
 export declare function assertRowFitsBindTarget(registry: Registry | undefined, bindTo: PendingFileRefBindTarget, row: FileRefRow): void;
+export declare function assertRowFitsFileField(row: FileRefRow, fieldDef: AnyFileFieldDef): void;
 export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-conflict";
 /**
  * Binds one of the caller's own pending uploads to a record from a custom handler, with the
@@ -53,4 +55,3 @@ export declare function bindPendingFileRef(args: PendingFileRefLookup & {
     readonly bindTo?: PendingFileRefBindTarget;
     readonly registry?: Registry;
 }): Promise<BindPendingFileRefOutcome>;
-export {};

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

@@ -1,19 +1,13 @@
 import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
-import { isFileField } from "../engine/field-helpers.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { FrameworkReasons, InternalError, reraiseAsKumikoError, UnprocessableError, } from "../errors/index.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { loadFileRefRows } from "./load-save-file-refs.js";
 import { validateFile } from "./types.js";
 import { resolveAttachedField } from "./upload-field-resolution.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));
-}
+export { fileRefIdsOf } from "./file-field-slots.js";
 function isPendingUploadFor(row, entityName, fieldName, user) {
     // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
     if (isAnonymousSessionUser(user))
@@ -60,11 +54,11 @@ export async function bindPendingFileRefs(args) {
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         return;
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef))
+        if (!holdsFileRefs(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])) {
+        for (const fileRefId of fileRefIdsInField(fieldDef, result.changes[fieldName])) {
             const row = fileRefRows.get(fileRefId);
             if (row === undefined)
                 continue;
@@ -117,14 +111,19 @@ export function assertRowFitsBindTarget(registry, bindTo, row) {
             message: `bindPendingFileRef: bindTo ${bindTo.entityName}.${bindTo.fieldName} is not a registered file field (pass the handler's ctx.registry)`,
         });
     }
+    assertRowFitsFileField(row, target.fieldDef);
+}
+// Same metadata check for any file slot a stored row lands in (a bind target, or an embedded
+// file sub-field a save names).
+export function assertRowFitsFileField(row, fieldDef) {
     const { storageKey, mimeType, size } = row;
     if (typeof storageKey !== "string" || typeof mimeType !== "string" || typeof size !== "number") {
         // A row without these can only come from corruption; letting it through would skip the check.
         throw new InternalError({
-            message: `bindPendingFileRef: pending file_ref ${String(row["id"])} lacks storageKey, mimeType or size`,
+            message: `file_ref ${String(row["id"])} lacks storageKey, mimeType or size`,
         });
     }
-    const error = validateFile({ fileName: storageKey, mimeType, size }, { maxSize: target.fieldDef.maxSize, accept: target.fieldDef.accept });
+    const error = validateFile({ fileName: storageKey, mimeType, size }, { maxSize: fieldDef.maxSize, accept: fieldDef.accept });
     if (error !== null) {
         throw new UnprocessableError(FrameworkReasons.fileViolatesBindTarget, {
             i18nKey: "errors.file.violatesBindTarget",

package/dist/files/bind-referenced-files.write.js

@@ -1,9 +1,8 @@
 import * as z from "zod";
-import { isFileField } from "../engine/field-helpers.js";
 import { defineWriteHandler, SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/index.js";
 import { ValidationError } from "../errors/index.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { loadFileRefRows } from "./load-save-file-refs.js";
 import { findImplicitEntityTable } from "./record-write-check.js";
@@ -36,7 +35,7 @@ function resolveFileBearingEntity(registry, entityType) {
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         throw invalidEntityType();
     const fileFieldNames = Object.entries(entity.fields)
-        .filter(([, fieldDef]) => isFileField(fieldDef))
+        .filter(([, fieldDef]) => holdsFileRefs(fieldDef))
         .map(([fieldName]) => fieldName);
     if (fileFieldNames.length === 0)
         throw invalidEntityType();
@@ -83,14 +82,15 @@ export const bindReferencedFilesWrite = defineWriteHandler({
         const { entityType, entityIds, limit } = event.payload;
         const { fileFieldNames, ...source } = resolveFileBearingEntity(ctx.registry, entityType);
         const records = await loadRecordPage(ctx.db, source, event.payload);
-        const referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOf(record[fieldName])));
+        const fileRefIdsOfRecordField = (record, fieldName) => fileRefIdsInField(source.entity.fields[fieldName], record[fieldName]);
+        const referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOfRecordField(record, fieldName)));
         const fileRefRows = await loadFileRefRows(ctx.db, referencedIds, event.user.tenantId);
         const executor = getFileRefExecutor();
         let bound = 0;
         let skipped = 0;
         for (const record of records) {
             for (const fieldName of fileFieldNames) {
-                for (const fileRefId of fileRefIdsOf(record[fieldName])) {
+                for (const fileRefId of fileRefIdsOfRecordField(record, fieldName)) {
                     const row = fileRefRows.get(fileRefId);
                     if (row === undefined ||
                         !isBindableToRecord(row, {

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

@@ -19,6 +19,8 @@ export type CreateFileRefInput = {
     readonly attachTo?: {
         readonly entityType: string;
         readonly fieldName: string;
+        /** File sub-field of the embedded `fieldName`, like POST /files' `subField` part. */
+        readonly subField?: string;
         readonly entityId?: string;
     };
     /** Byte limit replacing the configured default upload limit; a file field's own maxSize still applies first. */

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

@@ -42,6 +42,7 @@ export async function createFileRefFromBytes(ctx, input) {
         entityType: input.attachTo?.entityType,
         entityId: input.attachTo?.entityId,
         fieldName: input.attachTo?.fieldName,
+        subField: input.attachTo?.subField,
     });
     switch (outcome.kind) {
         case "created":
@@ -82,6 +83,7 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
         entityType: input.attachTo?.entityType,
         entityId: input.attachTo?.entityId,
         fieldName: input.attachTo?.fieldName,
+        subField: input.attachTo?.subField,
     });
     if (outcome.kind === "rejected")
         return fileRejectedFailure(outcome.error);

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

@@ -30,6 +30,8 @@ export type StoreFileInput = {
     readonly entityType?: string | undefined;
     readonly entityId?: string | undefined;
     readonly fieldName?: string | undefined;
+    /** File sub-field of the embedded `fieldName`; the stored row keeps the top-level `fieldName`. */
+    readonly subField?: string | undefined;
     /** Qualified name of a registered actionForm screen; `fieldName` then names one of its files
      *  fields and the upload is stored as pending (entityType = the screen QN, no entityId). */
     readonly actionForm?: string | undefined;

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

@@ -27,36 +27,32 @@ const ACTION_FORM_STORAGE_SEGMENT = "action-form";
 const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 class AttachTargetLockedError extends Error {
 }
-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).
+// 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).
+function invalidIdentifierError(input) {
+    const { entityType, entityId, fieldName, subField } = input;
     for (const [field, value] of [
         ["entityType", entityType],
         ["entityId", entityId],
         ["fieldName", fieldName],
+        ["subField", subField],
     ]) {
         if (value !== undefined && !SAFE_IDENTIFIER.test(value)) {
-            return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
+            return `invalid_${field}: must match /^[A-Za-z0-9_-]+$/`;
         }
     }
-    const field = resolveUploadField(deps.registry, input, deps.attachTargets);
-    if (field.kind === "rejected")
-        return field;
-    if (field.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 (subField !== undefined && (entityType === undefined || fieldName === undefined)) {
+        return "invalid_sub_field: subField requires entityType and fieldName";
     }
-    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
-    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
-    const accept = fieldDef?.accept;
-    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
-    if (validationError)
-        return rejected(validationError);
+    return undefined;
+}
+function acceptFileContent(input, accept) {
+    const { fileName, declaredMimeType, data } = input;
     const contentValidation = validateFileContent(fileName, data, accept);
-    if (contentValidation.kind === "rejected")
-        return rejected(contentValidation.error);
+    if (contentValidation.kind === "rejected") {
+        return { kind: "rejected", error: 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.
@@ -68,8 +64,9 @@ function acceptFile(deps, input) {
         };
     }
     const mimeTypeResolution = resolveUploadMimeType(fileName, declaredMimeType, data);
-    if (mimeTypeResolution.kind === "rejected")
-        return rejected(mimeTypeResolution.error);
+    if (mimeTypeResolution.kind === "rejected") {
+        return { kind: "rejected", error: mimeTypeResolution.error };
+    }
     return {
         kind: "accepted",
         mimeType: resolveContentType({
@@ -80,6 +77,26 @@ function acceptFile(deps, input) {
         extension: undefined,
     };
 }
+function acceptFile(deps, input) {
+    const { fileName, declaredMimeType, data } = input;
+    const rejected = (error) => ({ kind: "rejected", error });
+    const identifierError = invalidIdentifierError(input);
+    if (identifierError !== undefined)
+        return rejected(identifierError);
+    const field = resolveUploadField(deps.registry, input, deps.attachTargets);
+    if (field.kind === "rejected")
+        return field;
+    if (field.kind === "unresolvable") {
+        return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
+    }
+    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
+    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
+    const accept = fieldDef?.accept;
+    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
+    if (validationError)
+        return rejected(validationError);
+    return acceptFileContent(input, accept);
+}
 // Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
 // I/O doesn't belong inside a PG connection's tx window.
 export async function writeAcceptedFileBytes(deps, input) {