@cosmicdrift/kumiko-framework 0.399.0 → 0.400.0

package/agents/examples/inspection-checklist.md

@@ -0,0 +1,807 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/inspection-checklist. Do not edit. -->
+
+# inspection-checklist
+
+Embedded list as a phone inspection checklist: conditional fields, derived pass/fail, photos per row.
+
+## README
+
+# Inspection checklist
+
+An embedded list as a phone inspection checklist: the inspector walks fixed rows,
+enters a measurement or a result, and documents deviations with a finding and photos.
+
+## What it shows
+
+- **Conditional cells** (`src/entities/inspection-protocol.ts`): `visibleWhen` and
+  `requiredWhen` on sub-fields and on top-level fields. The server enforces
+  `requiredWhen` on create and update and answers with one `required` path per
+  missing cell (`checkpoints.0.finding`, `condition`).
+- **Pass/fail by range**: the derived `inRange` cell turns `measured`, `min` and `max`
+  into `ok` or `not_ok` (bounds included). The server recomputes it, so a client-sent
+  result never survives a value outside the range. `when` limits it to measurement rows;
+  a check row keeps the result the inspector picked.
+- **Photos per row**: an `images` sub-field. Upload with `entityType`, `fieldName` of the
+  embedded list and `subField` of the photo cell; files are bound, tenant-checked and
+  disposed like a top-level images field, always under the embedded list's field name.
+- **Fixed rows**: `inspection-protocol:create-from-plan` copies label, kind and limits from
+  a plan; the edit screen keeps those cells read-only and the row count fixed. It sets
+  `layout.width: "full"` because the default form width pushes result, finding and photos
+  behind horizontal scroll.
+
+## Source
+
+`src/feature.ts` wires the two entities, the handler and the screen. The integration test
+covers every behavior above over real HTTP.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Inspection Checklist Sample: Integration Test (conditional rows and derived result)
+// Proves, through real HTTP: server-enforced requiredWhen on rows and top-level fields and
+// the server-authoritative inRange cell.
+
+import { describe, expect, test } from "bun:test";
+import {
+  admin,
+  measurement,
+  PROTOCOL_CREATE,
+  PROTOCOL_UPDATE,
+  useInspectionStack,
+} from "./inspection-test-kit";
+
+const kit = useInspectionStack();
+const { pendingPhoto, createProtocol, checkpointsOf, storedResultOf } = kit;
+
+describe("requiredWhen on rows", () => {
+  test("a not_ok row without finding and photos is rejected with a path per cell", async () => {
+    const error = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [{ label: "Guard", kind: "check", result: "not_ok" }] },
+      admin,
+    );
+    expect(error.httpStatus).toBe(400);
+    expect(error.code).toBe("validation_error");
+    const paths = (error.details as { fields: { path: string }[] }).fields.map((f) => f.path);
+    expect(paths).toEqual(["checkpoints.0.finding", "checkpoints.0.photos"]);
+  });
+
+  test("a not_ok row with finding and photo is accepted", async () => {
+    const photo = await pendingPhoto();
+    const created = await createProtocol({
+      checkpoints: [
+        { label: "Guard", kind: "check", result: "not_ok", finding: "Cracked", photos: [photo] },
+      ],
+    });
+    expect((await checkpointsOf(created.id))[0]).toMatchObject({
+      result: "not_ok",
+      finding: "Cracked",
+      photos: [photo],
+    });
+  });
+});
+
+describe("inRange result", () => {
+  test("the server derives not_ok above and ok inside the range, bounds included", async () => {
+    const photo = await pendingPhoto();
+    const outside = measurement(210, { finding: "Too high", photos: [photo] });
+    expect(await storedResultOf(outside)).toBe("not_ok");
+    expect(await storedResultOf(measurement(190))).toBe("ok");
+    expect(await storedResultOf(measurement(180))).toBe("ok");
+    expect(await storedResultOf(measurement(200))).toBe("ok");
+  });
+
+  test("a client-sent ok never survives a measured value outside the range", async () => {
+    const photo = await pendingPhoto();
+    const row = measurement(210, { result: "ok", finding: "Too high", photos: [photo] });
+    expect(await storedResultOf(row)).toBe("not_ok");
+  });
+
+  test("requiredWhen sees the derived result, not the client-sent one", async () => {
+    const error = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [measurement(210, { result: "ok" })] },
+      admin,
+    );
+    expect(error.httpStatus).toBe(400);
+    const paths = (error.details as { fields: { path: string }[] }).fields.map((f) => f.path);
+    expect(paths).toEqual(["checkpoints.0.finding", "checkpoints.0.photos"]);
+  });
+
+  test("a manual result on a check row is kept", async () => {
+    const row = { label: "Guard", kind: "check", result: "ok" };
+    expect(await storedResultOf(row)).toBe("ok");
+  });
+});
+
+describe("requiredWhen on top-level fields", () => {
+  test("with_condition needs a condition on create and on update", async () => {
+    const onCreate = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [], continuedOperation: "with_condition" },
+      admin,
+    );
+    expect((onCreate.details as { fields: { path: string }[] }).fields[0]?.path).toBe("condition");
+
+    const created = await createProtocol({ checkpoints: [], continuedOperation: "yes" });
+    const onUpdate = await kit.stack.http.writeErr(
+      PROTOCOL_UPDATE,
+      { id: created.id, version: 1, changes: { continuedOperation: "with_condition" } },
+      admin,
+    );
+    expect(onUpdate.httpStatus).toBe(400);
+    expect((onUpdate.details as { fields: { path: string }[] }).fields[0]?.path).toBe("condition");
+
+    await kit.stack.http.writeOk(
+      PROTOCOL_UPDATE,
+      {
+        id: created.id,
+        version: 1,
+        changes: { continuedOperation: "with_condition", condition: "Daylight only" },
+      },
+      admin,
+    );
+  });
+
+  test("an unrelated update passes when the conditional fields are unchanged", async () => {
+    const created = await createProtocol({
+      checkpoints: [],
+      continuedOperation: "with_condition",
+      condition: "Daylight only",
+    });
+    await kit.stack.http.writeOk(
+      PROTOCOL_UPDATE,
+      { id: created.id, version: 1, changes: { measuringDevice: "Gauge 7" } },
+      admin,
+    );
+  });
+});
+```
+
+### src/__tests__/inspection-test-kit.ts
+
+```ts
+import { afterAll, beforeAll, expect } from "bun:test";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-testing/helpers";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-testing/stack";
+import { inspectionPlanEntity } from "../entities/inspection-plan";
+import { inspectionProtocolEntity } from "../entities/inspection-protocol";
+import { inspectionChecklistFeature } from "../feature";
+
+export const PROTOCOL_CREATE = "inspection-checklist:write:inspection-protocol:create";
+export const PROTOCOL_UPDATE = "inspection-checklist:write:inspection-protocol:update";
+export const PROTOCOL_DETAIL = "inspection-checklist:query:inspection-protocol:detail";
+export const PLAN_CREATE = "inspection-checklist:write:inspection-plan:create";
+export const CREATE_FROM_PLAN = "inspection-checklist:write:inspection-protocol:create-from-plan";
+
+const JPEG_BYTES = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(10).fill(0)]);
+const PDF_BYTES = new TextEncoder().encode("%PDF-1.4\n%test\n");
+
+export const UploadFiles = {
+  jpeg: { name: "pump.jpg", type: "image/jpeg", bytes: JPEG_BYTES },
+  pdf: { name: "report.pdf", type: "application/pdf", bytes: PDF_BYTES },
+} as const;
+
+const tenantId = testTenantId(1);
+export const admin = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+export const inspector = createTestUser({ id: 4, tenantId, roles: ["Inspector"] });
+export const viewer = createTestUser({ id: 2, tenantId, roles: ["Viewer"] });
+export const otherTenantAdmin = createTestUser({
+  id: 3,
+  tenantId: testTenantId(2),
+  roles: ["Admin"],
+});
+
+type User = typeof admin;
+export type Row = Record<string, unknown>;
+type Protocol = { readonly id: string; readonly version: number };
+
+export function measurement(measured: number | undefined, extra: Row = {}): Row {
+  return { label: "Pressure", kind: "measurement", min: 180, max: 200, measured, ...extra };
+}
+
+export function useInspectionStack() {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    patchFileInstanceofForBunTest();
+    stack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createFileFoundationFeature(),
+        createFilesFeature(),
+        inspectionChecklistFeature,
+      ],
+      files: { storageProvider: createInMemoryFileProvider() },
+    });
+    await unsafeCreateEntityTable(stack.db, inspectionPlanEntity, "inspection-plan");
+    await unsafeCreateEntityTable(stack.db, inspectionProtocolEntity, "inspection-protocol");
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  type UploadTarget = {
+    entityId?: string;
+    fieldName?: string;
+    subField?: string;
+    file?: (typeof UploadFiles)[keyof typeof UploadFiles];
+  };
+
+  async function upload(
+    asUser: User,
+    target: UploadTarget = { fieldName: "checkpoints", subField: "photos" },
+  ) {
+    const fd = new FormData();
+    fd.append("entityType", "inspection-protocol");
+    if (target.fieldName !== undefined) fd.append("fieldName", target.fieldName);
+    if (target.subField !== undefined) fd.append("subField", target.subField);
+    if (target.entityId !== undefined) fd.append("entityId", target.entityId);
+    const file = target.file ?? UploadFiles.jpeg;
+    fd.append("file", new File([Buffer.from(file.bytes)], file.name, { type: file.type }));
+    const { body, contentType } = await buildMultipartBody(fd);
+    const token = await stack.jwt.sign(asUser);
+    const res = await stack.app.request("/api/files", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+      body,
+    });
+    const json = (await res.json()) as { id?: string };
+    return { status: res.status, id: json.id ?? "" };
+  }
+
+  async function pendingPhoto(asUser: User = admin): Promise<string> {
+    const { status, id } = await upload(asUser);
+    expect(status).toBe(201);
+    return id;
+  }
+
+  async function pendingDocument(asUser: User = admin): Promise<string> {
+    const { status, id } = await upload(asUser, {
+      fieldName: "checkpoints",
+      subField: "documents",
+      file: UploadFiles.pdf,
+    });
+    expect(status).toBe(201);
+    return id;
+  }
+
+  async function fileStatus(fileId: string, asUser: User = admin): Promise<number> {
+    const token = await stack.jwt.sign(asUser);
+    const res = await stack.app.request(`/api/files/${fileId}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return res.status;
+  }
+
+  async function createProtocol(payload: Row, asUser: User = admin): Promise<Protocol> {
+    return stack.http.writeOk<Protocol>(PROTOCOL_CREATE, payload, asUser);
+  }
+
+  async function checkpointsOf(id: string): Promise<Row[]> {
+    const detail = await stack.http.queryOk<{ checkpoints: Row[] }>(PROTOCOL_DETAIL, { id }, admin);
+    return detail.checkpoints;
+  }
+
+  async function storedResultOf(row: Row): Promise<unknown> {
+    const created = await createProtocol({ checkpoints: [row] });
+    return (await checkpointsOf(created.id))[0]?.["result"];
+  }
+
+  return {
+    get stack() {
+      return stack;
+    },
+    upload,
+    pendingPhoto,
+    pendingDocument,
+    fileStatus,
+    createProtocol,
+    checkpointsOf,
+    storedResultOf,
+  };
+}
+```
+
+### src/__tests__/photos.integration.test.ts
+
+```ts
+// Inspection Checklist Sample: Integration Test (photos in a row, create-from-plan)
+// Proves, through real HTTP: pending upload with `subField`, binding under the embedded
+// field name, read access, tenant isolation, disposal and copying rows from a plan.
+
+import { describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  admin,
+  CREATE_FROM_PLAN,
+  otherTenantAdmin,
+  PLAN_CREATE,
+  PROTOCOL_CREATE,
+  PROTOCOL_UPDATE,
+  type Row,
+  useInspectionStack,
+  viewer,
+} from "./inspection-test-kit";
+
+const kit = useInspectionStack();
+const { upload, pendingPhoto, fileStatus, createProtocol, checkpointsOf } = kit;
+
+describe("photos inside a row", () => {
+  test("a pending upload is bound to the protocol under the top-level field name", async () => {
+    const photo = await pendingPhoto();
+    const created = await createProtocol({
+      checkpoints: [
+        { label: "Guard", kind: "check", result: "not_ok", finding: "Cracked", photos: [photo] },
+      ],
+    });
+
+    const [ref] = await selectMany(kit.stack.db, fileRefsTable, { id: photo });
+    expect(ref).toMatchObject({
+      entityType: "inspection-protocol",
+      entityId: created.id,
+      fieldName: "checkpoints",
+    });
+  });
+
+  test("reads: owner 200, other tenant 404, same tenant without read access denied", async () => {
+    const photo = await pendingPhoto();
+    await createProtocol({
+      checkpoints: [
+        { label: "Guard", kind: "check", result: "not_ok", finding: "Cracked", photos: [photo] },
+      ],
+    });
+    expect(await fileStatus(photo, admin)).toBe(200);
+    expect(await fileStatus(photo, otherTenantAdmin)).toBe(404);
+    expect(await fileStatus(photo, viewer)).toBe(404);
+  });
+
+  test("an upload against an existing record binds the file at once", async () => {
+    const created = await createProtocol({ checkpoints: [{ label: "Guard", kind: "check" }] });
+    const { status, id } = await upload(admin, {
+      entityId: created.id,
+      fieldName: "checkpoints",
+      subField: "photos",
+    });
+    expect(status).toBe(201);
+    const [ref] = await selectMany(kit.stack.db, fileRefsTable, { id });
+    expect(ref).toMatchObject({ entityId: created.id, fieldName: "checkpoints" });
+  });
+
+  test("file ids from another tenant or another protocol are rejected", async () => {
+    const foreign = await pendingPhoto(otherTenantAdmin);
+    const row = (photo: string): Row => ({
+      label: "Guard",
+      kind: "check",
+      result: "not_ok",
+      finding: "Cracked",
+      photos: [photo],
+    });
+    const foreignTenant = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [row(foreign)] },
+      admin,
+    );
+    expect([foreignTenant.httpStatus, foreignTenant.code]).toEqual([400, "validation_error"]);
+
+    const own = await pendingPhoto();
+    await createProtocol({ checkpoints: [row(own)] });
+    const otherProtocol = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [row(own)] },
+      admin,
+    );
+    expect([otherProtocol.httpStatus, otherProtocol.code]).toEqual([400, "validation_error"]);
+  });
+
+  test("removing a photo from a row disposes its file", async () => {
+    const keep = await pendingPhoto();
+    const drop = await pendingPhoto();
+    const row = (photos: string[]): Row => ({
+      label: "Guard",
+      kind: "check",
+      result: "not_ok",
+      finding: "Cracked",
+      photos,
+    });
+    const created = await createProtocol({ checkpoints: [row([keep, drop])] });
+
+    await kit.stack.http.writeOk(
+      PROTOCOL_UPDATE,
+      { id: created.id, version: 1, changes: { checkpoints: [row([keep])] } },
+      admin,
+    );
+
+    expect(await fileStatus(keep)).toBe(200);
+    expect(await fileStatus(drop)).toBe(404);
+  });
+
+  test("a subField that is not a file sub-field or not a plain name is a 400", async () => {
+    for (const subField of ["label", "a.b", "../x"]) {
+      const { status } = await upload(admin, { fieldName: "checkpoints", subField });
+      expect(status).toBe(400);
+    }
+  });
+});
+
+describe("create-from-plan", () => {
+  test("copies label, kind and limits and leaves the result empty", async () => {
+    const plan = await kit.stack.http.writeOk<{ id: string }>(
+      PLAN_CREATE,
+      {
+        name: "Monthly pump check",
+        checkpoints: [
+          { label: "Guard fitted", kind: "check" },
+          { label: "Pressure", kind: "measurement", min: 180, max: 200 },
+        ],
+      },
+      admin,
+    );
+
+    const created = await kit.stack.http.writeOk<{ id: string }>(
+      CREATE_FROM_PLAN,
+      { planId: plan.id },
+      admin,
+    );
+
+    expect(await checkpointsOf(created.id)).toEqual([
+      { label: "Guard fitted", kind: "check" },
+      { label: "Pressure", kind: "measurement", min: 180, max: 200 },
+    ]);
+  });
+});
+```
+
+### src/__tests__/sub-field-rules.integration.test.ts
+
+```ts
+// Inspection Checklist Sample: Integration Test (rules of single cells on save)
+// Proves, through real HTTP: a cell's write access is enforced when the record is saved, and a
+// file only lands in a file cell whose accept list it fits.
+
+import { describe, expect, test } from "bun:test";
+import {
+  admin,
+  inspector,
+  PROTOCOL_CREATE,
+  PROTOCOL_UPDATE,
+  type Row,
+  useInspectionStack,
+} from "./inspection-test-kit";
+
+const kit = useInspectionStack();
+
+// The same denial a top-level field with a write rule gets.
+const OWNERSHIP_DENIED = [422, "errors.ownershipDenied"];
+
+const check = (extra: Row = {}): Row => ({ label: "Guard", kind: "check", ...extra });
+
+describe("write access of a single cell", () => {
+  test("a user without the role cannot set the cell, on create or update", async () => {
+    const created = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      { checkpoints: [check({ approvedBy: "Me" })] },
+      inspector,
+    );
+    expect([created.httpStatus, created.i18nKey]).toEqual(OWNERSHIP_DENIED);
+
+    const protocol = await kit.createProtocol({ checkpoints: [check()] }, inspector);
+    const updated = await kit.stack.http.writeErr(
+      PROTOCOL_UPDATE,
+      { id: protocol.id, version: 1, changes: { checkpoints: [check({ approvedBy: "Me" })] } },
+      inspector,
+    );
+    expect([updated.httpStatus, updated.i18nKey]).toEqual(OWNERSHIP_DENIED);
+    expect(await kit.checkpointsOf(protocol.id)).toEqual([check()]);
+  });
+
+  test("the same user may save rows that leave the cell as it is", async () => {
+    const protocol = await kit.createProtocol({ checkpoints: [check({ approvedBy: "Boss" })] });
+    await kit.stack.http.writeOk(
+      PROTOCOL_UPDATE,
+      {
+        id: protocol.id,
+        version: 1,
+        changes: { checkpoints: [check({ approvedBy: "Boss", label: "Guard fitted" })] },
+      },
+      inspector,
+    );
+    expect(await kit.checkpointsOf(protocol.id)).toEqual([
+      check({ approvedBy: "Boss", label: "Guard fitted" }),
+    ]);
+  });
+
+  test("changing or clearing the cell on an existing row is denied, removing the row too", async () => {
+    const protocol = await kit.createProtocol({ checkpoints: [check({ approvedBy: "Boss" })] });
+    for (const checkpoints of [[check({ approvedBy: "Me" })], [check()], []]) {
+      const denied = await kit.stack.http.writeErr(
+        PROTOCOL_UPDATE,
+        { id: protocol.id, version: 1, changes: { checkpoints } },
+        inspector,
+      );
+      expect([denied.httpStatus, denied.i18nKey]).toEqual(OWNERSHIP_DENIED);
+    }
+    await kit.stack.http.writeOk(
+      PROTOCOL_UPDATE,
+      { id: protocol.id, version: 1, changes: { checkpoints: [check({ approvedBy: "Me" })] } },
+      admin,
+    );
+  });
+});
+
+describe("a file only lands in a cell it fits", () => {
+  test("a pdf uploaded to the loose cell is rejected in the photos cell", async () => {
+    const pdf = await kit.pendingDocument();
+    const denied = await kit.stack.http.writeErr(
+      PROTOCOL_CREATE,
+      {
+        checkpoints: [
+          check({ result: "not_ok", finding: "Cracked", photos: [pdf], documents: [pdf] }),
+        ],
+      },
+      admin,
+    );
+    expect([denied.httpStatus, denied.code]).toEqual([422, "unprocessable"]);
+  });
+
+  test("the same pdf is accepted where it was uploaded", async () => {
+    const pdf = await kit.pendingDocument();
+    const created = await kit.createProtocol({ checkpoints: [check({ documents: [pdf] })] });
+    expect(await kit.checkpointsOf(created.id)).toEqual([check({ documents: [pdf] })]);
+  });
+
+  test("moving a stored pdf from the documents cell to the photos cell is rejected", async () => {
+    const pdf = await kit.pendingDocument();
+    const created = await kit.createProtocol({ checkpoints: [check({ documents: [pdf] })] });
+    const denied = await kit.stack.http.writeErr(
+      PROTOCOL_UPDATE,
+      {
+        id: created.id,
+        version: 1,
+        changes: {
+          checkpoints: [check({ result: "not_ok", finding: "Cracked", photos: [pdf] })],
+        },
+      },
+      admin,
+    );
+    expect([denied.httpStatus, denied.code]).toEqual([422, "unprocessable"]);
+  });
+});
+```
+
+### src/entities/inspection-plan.ts
+
+```ts
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedListField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const inspectionPlanEntity = createEntity({
+  table: "read_sample_inspection_plans",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    checkpoints: createEmbeddedListField(
+      {
+        label: { type: "text", required: true },
+        kind: { type: "select", options: ["check", "measurement"], required: true },
+        min: { type: "number" },
+        max: { type: "number" },
+      },
+      { personal: false, reason: "is_business_data" },
+    ),
+  },
+});
+
+export const inspectionPlanTable = buildEntityTable("inspection-plan", inspectionPlanEntity);
+```
+
+### src/entities/inspection-protocol.ts
+
+```ts
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedListField,
+  createEntity,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const isMeasurement = { field: "kind", eq: "measurement" } as const;
+const isNotOk = { field: "result", eq: "not_ok" } as const;
+
+export const inspectionProtocolEntity = createEntity({
+  table: "read_sample_inspection_protocols",
+  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,
+          accept: ["jpg", "jpeg", "png"],
+          visibleWhen: isNotOk,
+          requiredWhen: isNotOk,
+        },
+        documents: { type: "files", maxCount: 3 },
+        approvedBy: { type: "text", access: { write: ["Admin"] } },
+      },
+      {
+        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" },
+    }),
+  },
+});
+
+export const inspectionProtocolTable = buildEntityTable(
+  "inspection-protocol",
+  inspectionProtocolEntity,
+);
+```
+
+### src/feature.ts
+
+```ts
+// Inspection Checklist Sample
+// Shows: an embedded list as a phone inspection checklist.
+//   - visibleWhen / requiredWhen on cells and top-level fields (server-enforced)
+//   - a derived pass/fail cell (inRange) that the server recomputes
+//   - an images cell per row, uploaded with the `subField` multipart part
+//   - fixed rows copied from a plan, only the result cells stay editable
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { inspectionPlanEntity } from "./entities/inspection-plan";
+import { inspectionProtocolEntity } from "./entities/inspection-protocol";
+import { createFromPlan } from "./handlers/create-from-plan.write";
+import { inspectionProtocolEditScreen } from "./screens/inspection-protocol-edit.screen";
+
+export { inspectionPlanEntity } from "./entities/inspection-plan";
+export { inspectionProtocolEntity } from "./entities/inspection-protocol";
+
+const inspectorAccess = { access: { roles: ["Admin", "Inspector"] } } as const;
+
+export const inspectionChecklistFeature = defineFeature("inspection-checklist", (r) => {
+  r.requires({ features: ["files"] });
+
+  r.crud("inspection-plan", inspectionPlanEntity, {
+    write: inspectorAccess,
+    read: inspectorAccess,
+  });
+  r.crud("inspection-protocol", inspectionProtocolEntity, {
+    write: inspectorAccess,
+    read: inspectorAccess,
+  });
+  r.writeHandler(createFromPlan);
+
+  r.screen(inspectionProtocolEditScreen);
+});
+```
+
+### src/handlers/create-from-plan.write.ts
+
+```ts
+import { createEntityExecutor, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { inspectionPlanEntity } from "../entities/inspection-plan";
+import { inspectionProtocolEntity } from "../entities/inspection-protocol";
+
+const { executor: planExecutor } = createEntityExecutor("inspection-plan", inspectionPlanEntity);
+const { executor: protocolExecutor } = createEntityExecutor(
+  "inspection-protocol",
+  inspectionProtocolEntity,
+);
+
+const planRows = z.array(
+  z.object({
+    label: z.string(),
+    kind: z.enum(["check", "measurement"]),
+    min: z.number().optional(),
+    max: z.number().optional(),
+  }),
+);
+
+// Copies only the plan's fixed columns; result, finding and photos stay empty for the inspector.
+export const createFromPlan = defineWriteHandler({
+  name: "inspection-protocol:create-from-plan",
+  schema: z.object({ planId: z.uuid() }),
+  access: { roles: ["Admin", "Inspector"] },
+  handler: async (event, ctx) => {
+    const plan = await planExecutor.detail({ id: event.payload.planId }, event.user, ctx.db);
+    if (!plan) return failNotFound("inspection-plan", event.payload.planId);
+    const checkpoints = planRows.parse(plan["checkpoints"]).map(({ label, kind, min, max }) => ({
+      label,
+      kind,
+      ...(min !== undefined ? { min } : {}),
+      ...(max !== undefined ? { max } : {}),
+    }));
+    return protocolExecutor.create({ checkpoints }, event.user, ctx.db);
+  },
+});
+```
+
+### src/screens/inspection-protocol-edit.screen.ts
+
+```ts
+import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export const inspectionProtocolEditScreen: EntityEditScreenDefinition = {
+  id: "inspection-protocol-edit",
+  type: "entityEdit",
+  entity: "inspection-protocol",
+  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"] },
+    ],
+  },
+};
+```