@cosmicdrift/kumiko-samples 0.399.0 → 0.400.0

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/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 }

package/samples/apps/styleguide/src/app/seed.ts

@@ -1,9 +1,14 @@
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import { buildEntityTable, createTenantDb, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { createEntityExecutor, createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileRefFromBytes,
+  createTenantFileContext,
+} from "@cosmicdrift/kumiko-framework/files";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 
 import { demoEntity } from "../features/demo/feature";
+import { inspectionEntity } from "../features/examples/feature";
 
 // Gives the list view real rows with status/flag variety. price (money)
 // stays empty — the money input shows in the edit screen, in the seed we leave
@@ -16,6 +21,8 @@ const STATUSES = ["draft", "review", "published", "archived"] as const;
 // otherwise change every run.
 export const FIRST_STYLEGUIDE_ITEM_ID = "00000000-0000-4000-8000-0000000000f1";
 
+export const FIRST_STYLEGUIDE_INSPECTION_ID = "00000000-0000-4000-8000-0000000000f2";
+
 const demoItemTable = buildEntityTable("item", demoEntity);
 
 export const seedStyleguideItems: SeedFn = async (stack) => {
@@ -58,3 +65,97 @@ export const seedStyleguideItems: SeedFn = async (stack) => {
     }
   }
 };
+
+const inspectionTable = buildEntityTable("inspection", inspectionEntity);
+
+// 1x1 PNG, enough for the thumbnail chain; the bytes only need to be a valid image.
+const SEED_PHOTO_PNG = Uint8Array.from(
+  Buffer.from(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+    "base64",
+  ),
+);
+
+// Fixed id for the inspection-checklist screenshot scenarios. Created through the executor like
+// the first demo item. Photos are real file refs attached to checkpoints.photos, created
+// server-side the way POST /files would (a not_ok checkpoint requires a photo).
+export const seedStyleguideInspection: SeedFn = async (stack) => {
+  if (await fetchOne(stack.db, inspectionTable, { id: FIRST_STYLEGUIDE_INSPECTION_ID })) return;
+  const tenantId = TestUsers.admin.tenantId;
+  const tenantDb = createTenantDb({ db: stack.db, tenantId });
+  const resolver = stack.context._fileProviderResolver;
+  const files = resolver ? createTenantFileContext(resolver, tenantId) : stack.context.files;
+
+  const photoIds: string[] = [];
+  for (const fileName of ["hose.png", "bearing.png"]) {
+    const photo = await createFileRefFromBytes(
+      {
+        db: tenantDb,
+        services: { files },
+        registry: stack.registry,
+        user: createSystemUser(tenantId),
+      },
+      {
+        fileName,
+        mimeType: "image/png",
+        data: SEED_PHOTO_PNG,
+        attachTo: {
+          entityType: "inspection",
+          fieldName: "checkpoints",
+          subField: "photos",
+          entityId: FIRST_STYLEGUIDE_INSPECTION_ID,
+        },
+      },
+    );
+    if (!photo.isSuccess) {
+      // biome-ignore lint/suspicious/noConsole: dev-seed surfaces failures in the runner log
+      console.error("[seed] styleguide inspection photo failed:", photo.error);
+      return;
+    }
+    photoIds.push(photo.data.id);
+  }
+
+  const { executor } = createEntityExecutor("inspection", inspectionEntity);
+  const res = await executor.create(
+    {
+      id: FIRST_STYLEGUIDE_INSPECTION_ID,
+      measuringDevice: "Torque wrench TW-200",
+      checkpoints: [
+        { label: "Guard fitted", kind: "check", result: "ok" },
+        {
+          label: "Hydraulic hose intact",
+          kind: "check",
+          result: "not_ok",
+          finding: "Hose chafed at the clamp, replace before next shift.",
+          photos: [photoIds[0]],
+        },
+        {
+          label: "Bolt torque (Nm)",
+          kind: "measurement",
+          min: 180,
+          max: 200,
+          measured: 190,
+          result: "ok",
+        },
+        {
+          label: "Bearing play (mm)",
+          kind: "measurement",
+          min: 0.05,
+          max: 0.2,
+          measured: 0.31,
+          result: "not_ok",
+          finding: "Play above tolerance, re-measure after re-seating.",
+          photos: [photoIds[1]],
+        },
+      ],
+      continuedOperation: "with_condition",
+      condition: "Operate at reduced load until the hose is replaced.",
+    },
+    TestUsers.admin,
+    tenantDb,
+  );
+  if (!res.isSuccess) {
+    // biome-ignore lint/suspicious/noConsole: dev-seed surfaces failures in the runner log
+    console.error("[seed] styleguide inspection failed:", res.error);
+  }
+};

package/samples/apps/styleguide/src/app/server.ts

@@ -22,7 +22,7 @@ import { aiTextDemoFeature } from "../features/widgets/ai-text-demo";
 import { widgetsFeature } from "../features/widgets/feature";
 import { workboardFeature } from "../features/workboard/feature";
 import { seedWorkboardTasks } from "../features/workboard/seed";
-import { seedStyleguideItems } from "./seed";
+import { seedStyleguideInspection, seedStyleguideItems } from "./seed";
 
 const configResolver = createConfigResolver();
 
@@ -46,7 +46,7 @@ await runDevApp({
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",
   watchDirs: ["./src", "../../../packages/*/src"],
-  seeds: [seedStyleguideItems, seedAiConnections, seedWorkboardTasks],
+  seeds: [seedStyleguideItems, seedStyleguideInspection, seedAiConnections, seedWorkboardTasks],
   extraContext: ({ registry }) => ({
     configResolver,
     configAccessorFactory: createConfigAccessorFactory(registry, configResolver),

package/samples/apps/styleguide/src/features/examples/feature.ts

@@ -6,6 +6,7 @@
 import {
   createBooleanField,
   createDateField,
+  createEmbeddedListField,
   createEntity,
   createImageField,
   createLocatedTimestampField,
@@ -70,6 +71,65 @@ export const deliveryEntity = createEntity({
   },
 });
 
+// Inspection — the inspection-checklist recipe's protocol (sub-fields, derived result,
+// conditions), rendered as the phone checklist in the auto-form.
+const isMeasurement = { field: "kind", eq: "measurement" } as const;
+const isNotOk = { field: "result", eq: "not_ok" } as const;
+
+export const inspectionEntity = createEntity({
+  table: "read_examples_inspection",
+  fields: {
+    measuringDevice: createTextField({ personal: false, reason: "is_business_data" }),
+    checkpoints: createEmbeddedListField(
+      {
+        label: { type: "text", required: true },
+        kind: { type: "select", options: ["check", "measurement"], required: true },
+        min: { type: "number", visibleWhen: isMeasurement },
+        max: { type: "number", visibleWhen: isMeasurement },
+        measured: { type: "number", visibleWhen: isMeasurement },
+        result: {
+          type: "select",
+          options: ["ok", "not_ok"],
+          display: "radio",
+          optionTones: { ok: "ok", not_ok: "bad" },
+        },
+        finding: { type: "text", visibleWhen: isNotOk, requiredWhen: isNotOk },
+        photos: {
+          type: "images",
+          capture: "environment",
+          maxCount: 5,
+          visibleWhen: isNotOk,
+          requiredWhen: isNotOk,
+        },
+      },
+      {
+        personal: false,
+        reason: "is_business_data",
+        derived: {
+          result: {
+            op: "inRange",
+            from: ["measured", "min", "max"],
+            inside: "ok",
+            outside: "not_ok",
+            when: isMeasurement,
+          },
+        },
+      },
+    ),
+    continuedOperation: createSelectField({
+      options: ["yes", "with_condition", "no"],
+      display: "radio",
+      optionTones: { yes: "ok", with_condition: "warn", no: "bad" },
+    }),
+    condition: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      visibleWhen: { field: "continuedOperation", eq: "with_condition" },
+      requiredWhen: { field: "continuedOperation", eq: "with_condition" },
+    }),
+  },
+});
+
 const openReason =
   "demo app: any signed-in user edits the shipping, profile and delivery example " +
   "forms; there is no per-user ownership in this sample";
@@ -194,6 +254,35 @@ export const examplesFeature = defineFeature("examples", (r) => {
     },
   });
 
+  r.crud("inspection", inspectionEntity, editFormOnly);
+
+  r.screen({
+    id: "inspection-edit",
+    type: "entityEdit",
+    entity: "inspection",
+    submitLabel: "examples:inspection:submit",
+    layout: {
+      width: "full",
+      sections: [
+        {
+          columns: 1,
+          fields: [
+            "measuringDevice",
+            {
+              field: "checkpoints",
+              embeddedList: {
+                readOnlyCells: ["label", "kind", "min", "max"],
+                cardHiddenCells: ["kind"],
+                fixedRows: true,
+              },
+            },
+          ],
+        },
+        { columns: 1, fields: ["continuedOperation", "condition"] },
+      ],
+    },
+  });
+
   r.nav({ id: "examples", label: "examples:nav.examples", icon: "folder", order: 30 });
   r.nav({
     id: "shipping",
@@ -219,4 +308,12 @@ export const examplesFeature = defineFeature("examples", (r) => {
     icon: "calendar",
     order: 30,
   });
+  r.nav({
+    id: "inspection",
+    label: "examples:nav.inspection",
+    parent: "examples:nav:examples",
+    screen: "examples:screen:inspection-edit",
+    icon: "file",
+    order: 40,
+  });
 });

package/samples/apps/styleguide/src/features/examples/i18n.ts

@@ -69,4 +69,51 @@ export const EXAMPLES_I18N: Readonly<Record<string, LocalizedString>> = {
     en: "Booked at (UTC instant)",
   },
   "examples:entity:delivery:field:homeZone": { de: "Heimatzone Kurier", en: "Courier home zone" },
+  "examples:nav.inspection": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.create.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.create.subtitle": {
+    de: "Prüfpunkte abhaken oder messen, bei Abweichung Befund und Fotos erfassen.",
+    en: "Check or measure each point, record a finding and photos on deviation.",
+  },
+  "screen:inspection-edit.edit.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.edit.subtitle": {
+    de: "Prüfpunkte abhaken oder messen, bei Abweichung Befund und Fotos erfassen.",
+    en: "Check or measure each point, record a finding and photos on deviation.",
+  },
+  "examples:inspection:submit": { de: "Protokoll speichern", en: "Save protocol" },
+  "examples:entity:inspection:field:measuringDevice": { de: "Messgerät", en: "Measuring device" },
+  "examples:entity:inspection:field:checkpoints": { de: "Prüfpunkte", en: "Checkpoints" },
+  "examples:entity:inspection:field:checkpoints:cell:label": { de: "Prüfpunkt", en: "Checkpoint" },
+  "examples:entity:inspection:field:checkpoints:cell:kind": { de: "Art", en: "Kind" },
+  "examples:entity:inspection:field:checkpoints:cell:min": { de: "Min", en: "Min" },
+  "examples:entity:inspection:field:checkpoints:cell:max": { de: "Max", en: "Max" },
+  "examples:entity:inspection:field:checkpoints:cell:measured": { de: "Messwert", en: "Measured" },
+  "examples:entity:inspection:field:checkpoints:cell:result": { de: "Ergebnis", en: "Result" },
+  "examples:entity:inspection:field:checkpoints:cell:finding": { de: "Befund", en: "Finding" },
+  "examples:entity:inspection:field:checkpoints:cell:photos": { de: "Fotos", en: "Photos" },
+  "examples:entity:inspection:field:continuedOperation": {
+    de: "Weiterbetrieb",
+    en: "Continued operation",
+  },
+  "examples:entity:inspection:field:condition": { de: "Auflage", en: "Condition" },
+  "examples:entity:inspection:field:checkpoints:cell:kind:option:check": {
+    de: "Sichtprüfung",
+    en: "Check",
+  },
+  "examples:entity:inspection:field:checkpoints:cell:kind:option:measurement": {
+    de: "Messung",
+    en: "Measurement",
+  },
+  "examples:entity:inspection:field:checkpoints:cell:result:option:ok": { de: "i.O.", en: "OK" },
+  "examples:entity:inspection:field:checkpoints:cell:result:option:not_ok": {
+    de: "n.i.O.",
+    en: "Not OK",
+  },
+  "examples:entity:inspection:field:continuedOperation:option:yes": { de: "Ja", en: "Yes" },
+  "examples:entity:inspection:field:continuedOperation:option:with_condition": {
+    de: "Mit Auflage",
+    en: "With condition",
+  },
+  "examples:entity:inspection:field:continuedOperation:option:no": { de: "Nein", en: "No" },
 };

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 89,
+  "featureCount": 90,
   "features": [
     {
       "name": "account-security",
@@ -914,6 +914,35 @@
         "recommended": false
       }
     },
+    {
+      "name": "documents",
+      "description": "Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to. A document is visible only through a linked record the viewer can read, and only while the record that owns its file is readable too, so linking never widens access to the file. Documents arrive through capture rules (a file saved into a configured field) or through the system-only import for migrations, which keeps the caller's id, refuses an id another record already uses, and stamps createdAt with the import time (issuedAt carries the business date; the event store does not backdate); users link, unlink, edit and delete them. Read a record's documents with for-record, count expired and expiring ones with expiry-overview, list them with an expiry state and an expiring filter with overview (the documents list screen), and add the documents tab to a record screen with documentsTab().",
+      "toggleableDefault": null,
+      "adoptsBundledLists": true,
+      "requires": [
+        "files"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [
+        "documents:write:filed-document:create",
+        "documents:write:filed-document:delete",
+        "documents:write:filed-document:update",
+        "documents:write:import",
+        "documents:write:link",
+        "documents:write:unlink"
+      ],
+      "uiHints": {
+        "displayLabel": "Documents",
+        "category": "data",
+        "recommended": false
+      }
+    },
     {
       "name": "feature-toggles",
       "description": "Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: \"shared\"` syncs the snapshot across instances whenever a `toggle-set` event is appended.",

package/samples/apps/use-all-bundled/kumiko/migrations/0058_documents.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_filed_document_links", "read_filed_documents"]
+}

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -12,7 +12,11 @@
 
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
-import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  FILE_STORAGE_PROVIDER_ENV,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { BUNDLED_LISTS } from "../bundled-lists";
 import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES, VALIDATE_BOOT_OPTIONS } from "../run-config";
 import { ADMIN_EMAIL, ADMIN_PASSWORD, BETA_TENANT_ID, DEV_TENANT_ID } from "./auth-constants";
@@ -31,7 +35,12 @@ export const devAppOptions = {
   // it stays out of APP_FEATURES. appScreensFeature places the user-profile screen.
   features: [...BOOT_FEATURES, appScreensFeature, notesFeature, invoiceReportsFeature],
   featureToggles: true,
-  validateBootOptions: VALIDATE_BOOT_OPTIONS,
+  // documents has a file field, so the boot gate wants a storage provider; the seeded
+  // file-foundation config selects the real one, so only the validation env names it.
+  validateBootOptions: {
+    ...VALIDATE_BOOT_OPTIONS,
+    env: { [FILE_STORAGE_PROVIDER_ENV]: "inmemory", ...process.env },
+  },
   bundledLists: BUNDLED_LISTS,
   port: Number.parseInt(process.env["PORT"] ?? "4186", 10),
   clientEntry: "./src/app/client.tsx",