@cosmicdrift/kumiko-samples 0.398.0 → 0.400.0

package/packages/bundled-features/src/documents/queries/for-record.query.ts

@@ -0,0 +1,74 @@
+import {
+  type AccessRule,
+  defineQueryHandler,
+  type HandlerContext,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DocumentsQueries } from "../constants.ts";
+import { type ForRecordPayload, forRecordPayloadSchema } from "../schemas.ts";
+import { linkedDocumentIds, listDocuments } from "./list-page.ts";
+
+const EMPTY_PAGE = { rows: [], nextCursor: null, total: 0 };
+const LIVE_ENTITIES = ["filed-document", "filed-document-link"];
+
+type Dispatching = Pick<HandlerContext, "dispatch">;
+
+async function documentsOfRecord(
+  ctx: Dispatching,
+  linkTargets: readonly string[],
+  payload: ForRecordPayload,
+) {
+  const { entityType, entityId, filter, filters, ...paging } = payload;
+  if (!linkTargets.includes(entityType)) return EMPTY_PAGE;
+  const ids = await linkedDocumentIds(ctx, { entityType, entityId });
+  if (ids.length === 0) return EMPTY_PAGE;
+  return listDocuments(ctx, {
+    ...paging,
+    filters: [
+      { field: "id", op: "in", value: ids },
+      ...(filter !== undefined ? [filter] : []),
+      ...(filters ?? []),
+    ],
+  });
+}
+
+export function createForRecordQuery(access: AccessRule, linkTargets: readonly string[]) {
+  return defineQueryHandler({
+    name: "for-record",
+    schema: forRecordPayloadSchema,
+    access,
+    liveEntities: LIVE_ENTITIES,
+    description:
+      "Lists the documents linked to one record, paged and filterable like the document list; a record the caller cannot read, or a type that takes no documents, yields an empty page.",
+    handler: async (query, ctx) => documentsOfRecord(ctx, linkTargets, query.payload),
+  });
+}
+
+export function forTypeQueryName(entityType: string): string {
+  return `for-${toKebab(entityType)}`;
+}
+
+export function forTypeQueryQn(entityType: string): string {
+  return `${DocumentsQueries.forRecord.replace(/for-record$/, "")}${forTypeQueryName(entityType)}`;
+}
+
+// A relatedList tab sends only the parent id, so the host type is fixed per query.
+export function createForTypeQuery(
+  access: AccessRule,
+  linkTargets: readonly string[],
+  entityType: string,
+) {
+  return defineQueryHandler({
+    name: forTypeQueryName(entityType),
+    schema: forRecordPayloadSchema.omit({ entityType: true, entityId: true }).extend({
+      id: forRecordPayloadSchema.shape.entityId,
+    }),
+    access,
+    liveEntities: LIVE_ENTITIES,
+    description: `Lists the documents linked to one ${entityType} record by its id, paged and filterable like the document list; it feeds the documents tab on the ${entityType} screen.`,
+    handler: async (query, ctx) => {
+      const { id, ...rest } = query.payload;
+      return documentsOfRecord(ctx, linkTargets, { ...rest, entityType, entityId: id });
+    },
+  });
+}

package/packages/bundled-features/src/documents/queries/list-page.ts

@@ -0,0 +1,51 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { DocumentsQueries } from "../constants.ts";
+
+const LINK_LIST = "documents:query:filed-document-link:list";
+const LINK_PAGE_SIZE = 200;
+
+const pageSchema = z.object({
+  rows: z.array(z.record(z.string(), z.unknown())),
+  nextCursor: z.string().nullable().optional(),
+  total: z.number().optional(),
+});
+export type ListPage = z.infer<typeof pageSchema>;
+
+export type ListFilter = { readonly field: string; readonly op: string; readonly value: unknown };
+
+export async function listDocuments(
+  ctx: Pick<HandlerContext, "dispatch">,
+  payload: Record<string, unknown>,
+): Promise<ListPage> {
+  return pageSchema.parse(await ctx.dispatch.query(DocumentsQueries.list, payload));
+}
+
+// Goes through the link list, so a record the caller cannot read yields no ids (the link's
+// parentRef gate), and a document is then fetched through the document list, which applies the
+// document's own read gate again.
+export async function linkedDocumentIds(
+  ctx: Pick<HandlerContext, "dispatch">,
+  target: { readonly entityType: string; readonly entityId: string },
+): Promise<string[]> {
+  const ids: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = pageSchema.parse(
+      await ctx.dispatch.query(LINK_LIST, {
+        filters: [
+          { field: "entityType", op: "eq", value: target.entityType },
+          { field: "entityId", op: "eq", value: target.entityId },
+        ],
+        limit: LINK_PAGE_SIZE,
+        ...(cursor !== undefined && { cursor }),
+      }),
+    );
+    for (const row of page.rows) {
+      const documentId = row["documentId"];
+      if (typeof documentId === "string") ids.push(documentId);
+    }
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor !== undefined);
+  return ids;
+}

package/packages/bundled-features/src/documents/queries/overview.query.ts

@@ -0,0 +1,45 @@
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { EXPIRING_FACET_VALUE } from "../constants.ts";
+import { expiryStateOf, expiryWindow } from "../expiry.ts";
+import { overviewPayloadSchema } from "../schemas.ts";
+import { type ListFilter, listDocuments } from "./list-page.ts";
+
+const EXPIRY_FILTER_FIELD = "expiry";
+
+// The "expiring" facet is a moving date window, which a facet on a stored field cannot
+// express; it becomes a validUntil bound here, expired documents included. A document
+// without a date never matches it.
+function toDocumentFilters(filters: readonly ListFilter[], horizon: string): readonly ListFilter[] {
+  return filters.flatMap((clause): ListFilter[] => {
+    if (clause.field !== EXPIRY_FILTER_FIELD) return [clause];
+    const wantsExpiring =
+      Array.isArray(clause.value) && clause.value.includes(EXPIRING_FACET_VALUE);
+    return wantsExpiring ? [{ field: "validUntil", op: "lte", value: horizon }] : [];
+  });
+}
+
+export function createOverviewQuery(access: AccessRule, expiringWithinDays: number) {
+  return defineQueryHandler({
+    name: "overview",
+    schema: overviewPayloadSchema,
+    access,
+    liveEntities: ["filed-document", "filed-document-link"],
+    description:
+      "Lists the documents the caller can read with an expiry state per row (expired, expiring, valid, none); the expiring filter returns expired and soon-expiring documents. Powers the documents list screen.",
+    handler: async (query, ctx) => {
+      const { filters, ...paging } = query.payload;
+      const window = expiryWindow(ctx, expiringWithinDays);
+      const page = await listDocuments(ctx, {
+        ...paging,
+        filters: toDocumentFilters(filters ?? [], window.horizon),
+      });
+      return {
+        ...page,
+        rows: page.rows.map((row) => ({
+          ...row,
+          expiry: expiryStateOf(row["validUntil"], window),
+        })),
+      };
+    },
+  });
+}

package/packages/bundled-features/src/documents/schemas.ts

@@ -0,0 +1,66 @@
+import * as z from "zod";
+
+export const documentLinkPayloadSchema = z.object({
+  documentId: z.uuid(),
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+});
+export type DocumentLinkPayload = z.infer<typeof documentLinkPayloadSchema>;
+
+const isoDate = z.iso.date();
+
+export const importDocumentPayloadSchema = z.object({
+  id: z.uuid(),
+  title: z.string().trim().min(1).max(200),
+  category: z.string().min(1),
+  issuedAt: isoDate.optional(),
+  validUntil: isoDate.optional(),
+  fileRefId: z.uuid(),
+  links: z.array(
+    z.object({ entityType: z.string().min(1).max(64), entityId: z.string().min(1).max(128) }),
+  ),
+  deleted: z.boolean().optional(),
+});
+export type ImportDocumentPayload = z.infer<typeof importDocumentPayloadSchema>;
+
+export const forRecordPayloadSchema = z.object({
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+  limit: z.number().int().nonnegative().max(200).optional(),
+  cursor: z.string().optional(),
+  offset: z.number().int().nonnegative().optional(),
+  search: z.string().optional(),
+  sort: z.string().optional(),
+  sortDirection: z.enum(["asc", "desc"]).optional(),
+  totalCount: z.boolean().optional(),
+  filter: z
+    .object({
+      field: z.string(),
+      op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+      value: z.unknown(),
+    })
+    .optional(),
+  filters: z
+    .array(
+      z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        value: z.unknown(),
+      }),
+    )
+    .optional(),
+});
+export type ForRecordPayload = z.infer<typeof forRecordPayloadSchema>;
+
+export const overviewPayloadSchema = forRecordPayloadSchema.omit({
+  entityType: true,
+  entityId: true,
+  filter: true,
+});
+export type OverviewPayload = z.infer<typeof overviewPayloadSchema>;
+
+export const expiryOverviewPayloadSchema = z.object({
+  entityType: z.string().min(1).max(64).optional(),
+  entityId: z.string().min(1).max(128).optional(),
+});
+export type ExpiryOverviewPayload = z.infer<typeof expiryOverviewPayloadSchema>;

package/packages/bundled-features/src/documents/screens.ts

@@ -0,0 +1,86 @@
+import {
+  type AccessRule,
+  i18nKey,
+  type ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENTS_LIST_SCREEN_ID, DocumentsQueries, EXPIRING_FACET_VALUE } from "./constants.ts";
+
+// The columns every document list shows; the tab and the standalone screen stay alike.
+export const DOCUMENT_COLUMNS = ["title", "category", "validUntil", "file"] as const;
+
+const FIELD_PREFIX = "documents:entity:filed-document:field:";
+const CATEGORY_OPTION_PREFIX = `${FIELD_PREFIX}category:option:`;
+
+// A projectionList, not an entityList: the expiry state and its "expiring" filter are computed
+// per request from a moving date window, which an entityList's facets on stored fields cannot
+// express. The overview query still reads through the document list, so the read gate holds.
+export function createDocumentListScreen(
+  access: AccessRule,
+  categories: readonly string[],
+): ProjectionListScreenDefinition {
+  return {
+    id: DOCUMENTS_LIST_SCREEN_ID,
+    type: "projectionList",
+    query: DocumentsQueries.overview,
+    columns: [
+      { field: "title", label: `${FIELD_PREFIX}title` },
+      {
+        field: "category",
+        label: `${FIELD_PREFIX}category`,
+        renderer: { format: "enumOption", keyPrefix: CATEGORY_OPTION_PREFIX },
+      },
+      {
+        field: "validUntil",
+        label: `${FIELD_PREFIX}validUntil`,
+        renderer: { format: "date", dateStyle: "medium" },
+      },
+      {
+        field: "expiry",
+        label: "documents:list.facet.expiry",
+        sortable: false,
+        hideOnNarrow: true,
+        renderer: { format: "enumOption", keyPrefix: "documents:list.expiry." },
+      },
+      {
+        field: "file",
+        label: `${FIELD_PREFIX}file`,
+        sortable: false,
+        renderer: { format: "file" },
+      },
+    ],
+    pagination: "pages",
+    defaultSort: { field: "validUntil", dir: "asc" },
+    searchable: true,
+    facets: [
+      {
+        field: "category",
+        type: "select",
+        label: `${FIELD_PREFIX}category`,
+        options: categories.map((value) => ({
+          value,
+          label: `${CATEGORY_OPTION_PREFIX}${value}`,
+        })),
+      },
+      {
+        field: "expiry",
+        type: "select",
+        label: "documents:list.facet.expiry",
+        options: [{ value: EXPIRING_FACET_VALUE, label: "documents:list.facet.expiring" }],
+      },
+    ],
+    rowActions: [
+      {
+        kind: "writeHandler",
+        id: "delete",
+        label: i18nKey("kumiko.actions.delete"),
+        handler: "documents:write:filed-document:delete",
+        payload: { pick: ["id"] },
+        confirm: i18nKey("kumiko.actions.delete-confirm"),
+        style: "danger",
+      },
+    ],
+    access,
+    // The app places it with r.nav("documents:screen:list").
+    dormant: true,
+  };
+}

package/packages/bundled-features/src/documents/tab.ts

@@ -0,0 +1,46 @@
+import type { EditRelatedListSection } from "@cosmicdrift/kumiko-framework/engine";
+import type { DashboardStatPanel } from "@cosmicdrift/kumiko-framework/ui-types";
+import { DocumentsQueries } from "./constants.ts";
+import { forTypeQueryQn } from "./queries/for-record.query.ts";
+
+// "Documents" tab for the edit screen of a link target. The tab id is the same on every screen,
+// so deep links like ?tab=documents work across hosts.
+export function documentsTab(entityType: string): EditRelatedListSection {
+  return {
+    id: "documents",
+    kind: "relatedList",
+    title: "documents:tab.title",
+    query: forTypeQueryQn(entityType),
+    entity: "documents:document",
+    columns: [
+      { field: "title", sortable: true },
+      { field: "category", sortable: true },
+      { field: "validUntil", sortable: true },
+      { field: "file" },
+    ],
+    searchable: true,
+    count: true,
+  };
+}
+
+// Stat tiles for a dashboard: how many readable documents are expired or about to expire.
+export function documentExpiryPanels(): readonly DashboardStatPanel[] {
+  return [
+    {
+      kind: "stat",
+      id: "documents-expired",
+      label: "documents:overview.expired",
+      query: DocumentsQueries.expiryOverview,
+      valueField: "expired",
+      tone: "negative",
+    },
+    {
+      kind: "stat",
+      id: "documents-expiring",
+      label: "documents:overview.expiring",
+      query: DocumentsQueries.expiryOverview,
+      valueField: "expiring",
+      tone: "warn",
+    },
+  ];
+}

package/packages/bundled-features/src/documents/target-write-check.ts

@@ -0,0 +1,41 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  hasAccess,
+  type Registry,
+  type SessionUser,
+  toKebab,
+  userCanWriteFieldRow,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { parentRowIsVisible } from "../shared/index.ts";
+
+function updateHandlerAccessOf(registry: Registry, entityType: string) {
+  const suffix = `:write:${toKebab(entityType)}:update`;
+  for (const [qn, handler] of registry.getAllWriteHandlers()) {
+    if (qn.endsWith(suffix) && registry.getHandlerEntity(qn) === entityType) return handler.access;
+  }
+  return undefined;
+}
+
+// Linking a document changes what readers of the target see, so it needs what saving the target
+// needs: read visibility, the entity's update handler and its row-level write rule. A target that
+// is not visible answers like a missing one.
+export async function canWriteLinkTarget(
+  registry: Registry,
+  entityType: string,
+  entityId: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  if (!(await parentRowIsVisible(registry, entityType, entityId, user, db))) return false;
+  const entity = registry.getEntity(entityType);
+  if (entity === undefined) return false;
+  const updateAccess = updateHandlerAccessOf(registry, entityType);
+  if (updateAccess === undefined || !hasAccess(user, updateAccess)) return false;
+  const row = await createEntityExecutor(entityType, entity).executor.detail(
+    { id: entityId },
+    user,
+    db,
+  );
+  return row !== null && userCanWriteFieldRow(user, entity.access?.write, row, row);
+}

package/packages/bundled-features/src/documents/write-guard.ts

@@ -0,0 +1,59 @@
+import {
+  type DeleteContext,
+  type HandlerContext,
+  type PreSaveHookFn,
+  SYSTEM_ROLE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { DOCUMENT_ENTITY } from "./constants.ts";
+import type { DocumentExecutors } from "./executor.ts";
+import { canWriteLinkTarget } from "./target-write-check.ts";
+
+const LINK_PAGE_SIZE = 200;
+
+// Editing or deleting a document changes what every reader of its hosts sees, so it needs what
+// unlink needs: write access to at least one host it is linked to. Admin roles see unlinked
+// documents too and must be able to clean them up, and SYSTEM jobs (import, capture) write on
+// their own authority. A refused caller gets "not found", like a document they cannot read.
+export function createDocumentWriteGuard(
+  executors: DocumentExecutors,
+  adminRoles: readonly string[],
+) {
+  async function assertMayWrite(documentId: string, ctx: HandlerContext): Promise<void> {
+    const { user } = ctx;
+    if (user.roles.includes(SYSTEM_ROLE) || user.roles.some((role) => adminRoles.includes(role))) {
+      // skip: exempt roles write on their own authority
+      return;
+    }
+    let offset = 0;
+    for (;;) {
+      const page = await executors.link.list(
+        {
+          filters: [{ field: "documentId", op: "eq", value: documentId }],
+          limit: LINK_PAGE_SIZE,
+          offset,
+        },
+        user,
+        ctx.db,
+      );
+      for (const row of page.rows) {
+        const entityType = String(row["entityType"]);
+        const entityId = String(row["entityId"]);
+        // skip: one writable host is enough
+        if (await canWriteLinkTarget(ctx.registry, entityType, entityId, user, ctx.db)) return;
+      }
+      if (page.rows.length < LINK_PAGE_SIZE) break;
+      offset += LINK_PAGE_SIZE;
+    }
+    throw new NotFoundError(DOCUMENT_ENTITY, documentId);
+  }
+
+  const beforeUpdate: PreSaveHookFn = async (changes, ctx) => {
+    if (!ctx.isNew) await assertMayWrite(String(ctx.previous["id"]), ctx);
+    return changes;
+  };
+  const beforeDelete = async (payload: DeleteContext, ctx: HandlerContext): Promise<void> => {
+    await assertMayWrite(String(payload.id), ctx);
+  };
+  return { beforeUpdate, beforeDelete };
+}

package/packages/bundled-features/src/metrics/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Metric access roles and group names from a source table",
+    "detail": "A metric declares `access: { roles }` to open its tenant query to roles other than the admin roles; an empty list fails boot validation and no `access` keeps the admin-only default. A `groupBy` metric on an entity-table source whose column is a single reference names the rows after the referenced row's label field; the lookup runs through the caller's read access on the target entity, so unreadable or foreign-tenant rows keep their key, and static `groupLabels` still win."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/metrics/compute.ts

@@ -26,6 +26,10 @@ export type MetricRunParams = {
   readonly filterWhere: WhereObject;
   /** Extra filter that narrows the source to the caller's scope. */
   readonly scopeWhere: WhereObject;
+  /** Names for referenced-row group keys; absent where the caller cannot resolve them (system scope). */
+  readonly referenceLabels?: (
+    keys: readonly AggregateKey[],
+  ) => Promise<ReadonlyMap<string, string>>;
 };
 
 const NULL_KEY_TEXT = "—";
@@ -153,6 +157,7 @@ function buildRows(
   aggregates: MetricAggregates,
   total: number | null,
   labelOf: (key: string) => string,
+  groupLabelOf: (key: string) => string,
 ): readonly MetricRow[] {
   const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
   return aggregates.groups.map((row) => {
@@ -161,7 +166,7 @@ function buildRows(
     return {
       id: key,
       key,
-      label: labelOf(key),
+      label: groupLabelOf(key),
       value: rowValue,
       fraction: fractionOf(rowValue, total),
       ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
@@ -188,6 +193,15 @@ function buildSeries(
   }));
 }
 
+async function resolveReferencedGroupLabels(
+  metric: MetricDefinition,
+  params: MetricRunParams,
+  groups: readonly AggregateRow[],
+): Promise<ReadonlyMap<string, string>> {
+  if (params.referenceLabels === undefined || metric.groupBy === undefined) return new Map();
+  return params.referenceLabels(groups.map((row) => row.keys[0] ?? null));
+}
+
 export async function runMetric(
   db: TenantDb,
   metric: MetricDefinition,
@@ -230,7 +244,10 @@ export async function runMetric(
           ),
         )
       : [];
-  const rows = buildRows(metric, aggregates, value, labelOf);
+  const referencedLabels = await resolveReferencedGroupLabels(metric, params, aggregates.groups);
+  const groupLabelOf = (key: string): string =>
+    metric.groupLabels?.[key] ?? referencedLabels.get(key) ?? key;
+  const rows = buildRows(metric, aggregates, value, labelOf, groupLabelOf);
 
   return {
     value,

package/packages/bundled-features/src/metrics/feature.ts

@@ -1,9 +1,11 @@
+import { extractTableInfo } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   defineFeature,
   defineQueryHandler,
   type FeatureDefinition,
   type QueryHandlerDefinition,
+  referenceGroupLabels,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -78,7 +80,7 @@ function createTenantMetricQuery(
     name: metric.id,
     description: metric.description,
     schema: tenantPayloadSchema(metric),
-    access: { roles: access.admin },
+    access: { roles: metric.access?.roles ?? access.admin },
     handler: async (query, ctx) =>
       runMetric(ctx.db, metric, {
         range: query.payload.range,
@@ -87,6 +89,17 @@ function createTenantMetricQuery(
         filterWhere: await resolveMetricFilterWhere(metric, query.payload, ctx),
         // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
         scopeWhere: { tenantId: query.user.tenantId },
+        referenceLabels: (keys) =>
+          metric.groupBy === undefined
+            ? Promise.resolve(new Map())
+            : referenceGroupLabels(
+                ctx,
+                query.user,
+                extractTableInfo(metric.source).name,
+                metric.groupBy,
+                keys,
+                ctx.db,
+              ),
       }),
   });
 }

package/packages/bundled-features/src/metrics/types.ts

@@ -41,8 +41,10 @@ export type MetricDefinition = {
   readonly groupBy?: string;
   /** Second dimension, becomes `rows[].segments`; only without bucket. */
   readonly stackBy?: string;
-  /** Key value → i18n key, applied to groupBy and stackBy keys. */
+  /** Key value → i18n key, applied to groupBy and stackBy keys. Without an entry, a groupBy that is a single reference of an entity-table source is named after the referenced row (tenant scope, through the caller's read access); otherwise the key stays. */
   readonly groupLabels?: Readonly<Record<string, string>>;
+  /** Roles that may read the tenant query; default is the admin roles. Ignored for scope "system", which stays SystemAdmin only. */
+  readonly access?: { readonly roles: readonly string[] };
   readonly scopes: readonly MetricScope[];
 };
 

package/packages/bundled-features/src/metrics/validate.ts

@@ -31,6 +31,9 @@ function validateMetric(metric: MetricDefinition): void {
   };
   if (!KEBAB_ID.test(metric.id)) fail("has an id that is not kebab-case");
   if (metric.scopes.length === 0) fail("declares no scopes");
+  if (metric.access !== undefined && metric.access.roles.length === 0) {
+    fail("declares access with an empty roles list");
+  }
 
   const info = extractTableInfo(metric.source);
   validateColumns(metric, info, fail);

package/packages/bundled-features/src/shared/purge-row-file-refs.ts

@@ -1,6 +1,6 @@
 import { type DbRunner, selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
 import type { EntityDefinition, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { fileRefsTable, holdsFileRefs } from "@cosmicdrift/kumiko-framework/files";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 
 type EntityFields = EntityDefinition["fields"];
@@ -23,8 +23,9 @@ export type FileRefPurgeOutcome = "purged" | "missing_file_storage" | "file_dele
 
 const NO_FILE_FIELDS: FileFieldPlan = { singleFields: [], multiFields: [] };
 
-// Same set as boot-validator/entity-handler.ts FILE_FIELD_TYPES; the single/multi split
-// matters here because only plural fields resolve through file_refs.
+// Same set as boot-validator/entity-handler.ts FILE_FIELD_TYPES plus embedded fields with file
+// sub-fields; the single/multi split matters here because only plural fields resolve through
+// file_refs, bound under the top-level field name.
 export function planFileFields(
   fields: EntityFields,
   fieldNames?: readonly string[],
@@ -34,7 +35,7 @@ export function planFileFields(
   for (const [name, field] of Object.entries(fields)) {
     if (fieldNames !== undefined && !fieldNames.includes(name)) continue;
     if (field.type === "file" || field.type === "image") singleFields.push(name);
-    else if (field.type === "files" || field.type === "images") multiFields.push(name);
+    else if (holdsFileRefs(field)) multiFields.push(name);
   }
   return singleFields.length > 0 || multiFields.length > 0
     ? { singleFields, multiFields }