@cosmicdrift/kumiko-framework 0.316.0 → 0.318.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.316.0",
+  "version": "0.318.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.316.0",
-    "@cosmicdrift/kumiko-types": "0.316.0",
+    "@cosmicdrift/kumiko-http": "0.318.0",
+    "@cosmicdrift/kumiko-types": "0.318.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.316.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.318.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -1237,3 +1237,21 @@ export async function deleteManyBatched(
 export async function transaction<T>(db: AnyDb, fn: (tx: BunDbRunner) => Promise<T>): Promise<T> {
   return (await asRawClient(db).begin(async (tx) => fn(tx as BunDbRunner))) as T;
 }
+
+// A tx/savepoint handle has no begin(); fail closed instead of nesting silently or TypeError-ing.
+export async function runInNewTransaction<T>(
+  db: unknown,
+  fn: (tx: DbRunner) => Promise<T>,
+): Promise<T> {
+  const raw = asRawClient(db) as unknown as {
+    begin?: <TResult>(cb: (tx: unknown) => Promise<TResult>) => Promise<TResult>;
+  };
+  if (typeof raw.begin !== "function") {
+    throw new InternalError({
+      message:
+        "runInNewTransaction: runner has no begin() — already inside a transaction or savepoint.",
+    });
+  }
+  // @cast-boundary driver tx handle → DbRunner at the single seam
+  return raw.begin((tx) => fn(tx as DbRunner));
+}

package/src/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.318.0",
+    "type": "improvement",
+    "title": "Generic create/update entity handlers can exclude individual fields",
+    "detail": "`excludeFields` on defineEntityCreateHandler/defineEntityUpdateHandler, and `excludeFields: { create?, update? }` on registerEntityCrud/r.crud. A payload that still carries an excluded field fails validation instead of being stripped silently, so an app no longer needs a hand-written handler just to make one field read-only (e.g. a VIN after creation)."
+  },
+  {
+    "version": "0.317.0",
+    "type": "fix",
+    "title": "Changeset block parser keeps blank lines inside a multiline field",
+    "detail": "A blank line inside a `detail:`/`migration:` `|` block ended the\ncontinuation early because the check only looked for a leading two-space\nindent. The next indented line then no longer matched `key: value` on its\nown and parseChangesetChanges threw \"invalid kumiko-changes line\" instead\nof the real cause. Blank lines inside the block are now kept as paragraph\nbreaks in the field value."
+  },
+  {
+    "version": "0.317.0",
+    "type": "breaking",
+    "title": "\"files: a valid upload (png/jpeg/gif/webp/pdf/doc/docx) under the wrong extension is normalized to its real type instead of rejected, when that type is in the field's accept list or the upload has no accept restriction at all\"",
+    "detail": "A real PNG or WebP saved with a .jpg extension (a common case for renamed\nscreenshots or messenger downloads) was rejected with content_mismatch\neven when the field's accept explicitly allows png/webp, or when the upload\nis unattached and has no accept restriction at all. validateFileContent now\nalso accepts the field's accept list; when the sniffed byte signature\ndoesn't match the declared extension but the sniffed type's own extension is\nin accept, the upload proceeds under the sniffed mimeType with a storage key\nbuilt from the corrected extension, and the response reports the corrected\nmimeType. When there is no accept restriction at all, any recognized\nsignature (png, jpeg, gif, webp, pdf, doc, docx) normalizes the same way.\nThe original filename is kept as the display name. A sniffed type whose\nextension is not in a non-empty accept is still rejected with\ncontent_mismatch.",
+    "migration": "validateFileContent's signature changes from (fileName: string, content: Uint8Array): string | null to (fileName: string, content: Uint8Array, accept?: readonly string[]): FileContentValidationResult ({kind:\"ok\"} | {kind:\"normalized\", extension, mimeType} | {kind:\"rejected\", error}). A direct caller that checked \"if (result)\" for an error must switch to checking result.kind === \"rejected\" and reading result.error — every branch of the new return type is a truthy object, so an unmigrated truthy check would now reject every upload. No caller besides the built-in POST /api/files route calls this function directly today (checked across kumiko-framework, kumiko-enterprise, kumiko-platform, kumiko-studio and every app consumer). buildStorageKey gains an optional trailing extensionOverride parameter; existing calls without it are unaffected."
+  },
+  {
+    "version": "0.317.0",
+    "type": "improvement",
+    "title": "runInOwnTransaction(tenantDb, fn) runs fn in a fresh transaction on a TenantDb's pool runner",
+    "detail": "Exported from @cosmicdrift/kumiko-framework/db. fn receives a TenantDb with the same tenant, mode and grants bound to the new transaction. Fails closed for a TenantDb not built by createTenantDb, a memberReadOnly TenantDb, and a runner that is already inside a transaction."
+  },
   {
     "version": "0.316.0",
     "type": "fix",

package/src/db/__tests__/run-in-own-transaction.integration.test.ts

@@ -0,0 +1,166 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { createBooleanField, createEntity, createTextField } from "../../engine";
+import { AccessDeniedError, InternalError } from "../../errors";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import type { TableColumns } from "../dialect";
+import { buildEntityTable } from "../table-builder";
+import {
+  assertPersonalDataWrite,
+  createTenantDb,
+  type PersonalDataGate,
+  runInOwnTransaction,
+} from "../tenant-db";
+
+const entity = createEntity({
+  table: "run_in_own_tx_items",
+  fields: {
+    name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    isActive: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+});
+
+const table: TableColumns = buildEntityTable("runInOwnTxItem", entity);
+
+let testDb: TestDb;
+const tenant1 = TestUsers.admin; // tenantId: 1
+const tenant2 = TestUsers.otherTenant; // tenantId: 2
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, entity, "runInOwnTxItem");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("runInOwnTransaction", () => {
+  test("the tenant filter holds on the tx-bound db", async () => {
+    const tdb1 = createTenantDb(testDb.db, tenant1.tenantId);
+    const tdb2 = createTenantDb(testDb.db, tenant2.tenantId);
+    const marker = `shared-name-${crypto.randomUUID()}`;
+    await tdb2.insertOne(table, { name: marker });
+
+    const rows = await runInOwnTransaction(tdb1, async (txDb) => {
+      await txDb.insertOne(table, { name: marker });
+      return txDb.selectMany(table, { name: marker });
+    });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!["tenantId"]).toBe(testTenantId(1));
+  });
+
+  test("a throw in fn rolls back the tx's own writes", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+    const marker = `rollback-${crypto.randomUUID()}`;
+
+    await expect(
+      runInOwnTransaction(tdb, async (txDb) => {
+        await txDb.insertOne(table, { name: marker });
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    const rows = await tdb.selectMany(table, { name: marker });
+    expect(rows).toHaveLength(0);
+  });
+
+  test("commits the tx's writes on success", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+    const marker = `commit-${crypto.randomUUID()}`;
+
+    await runInOwnTransaction(tdb, async (txDb) => {
+      await txDb.insertOne(table, { name: marker });
+    });
+
+    const rows = await tdb.selectMany(table, { name: marker });
+    expect(rows).toHaveLength(1);
+  });
+
+  test("throws InternalError for a TenantDb not built by createTenantDb", async () => {
+    const handBuilt = { tenantId: testTenantId(1), mode: "tenant" } as unknown as TenantDb;
+
+    await expect(runInOwnTransaction(handBuilt, async () => undefined)).rejects.toThrow(
+      InternalError,
+    );
+  });
+
+  test("throws InternalError for a throwing guard Proxy, without the proxy's get trap firing", async () => {
+    let getTrapFired = false;
+    const guardProxy = new Proxy(
+      {},
+      {
+        get() {
+          getTrapFired = true;
+          throw new Error("systemScope guard: property access denied");
+        },
+      },
+    ) as unknown as TenantDb;
+
+    await expect(runInOwnTransaction(guardProxy, async () => undefined)).rejects.toThrow(
+      InternalError,
+    );
+    expect(getTrapFired).toBe(false);
+  });
+
+  test("throws InternalError for a memberReadOnly TenantDb", async () => {
+    const tdb = createTenantDb(
+      testDb.db,
+      tenant1.tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { memberReadOnly: true },
+    );
+
+    await expect(runInOwnTransaction(tdb, async () => undefined)).rejects.toThrow(InternalError);
+  });
+
+  test("throws InternalError when the runner has no begin() (already inside a transaction)", async () => {
+    const tdb = createTenantDb(testDb.db, tenant1.tenantId);
+
+    await expect(
+      runInOwnTransaction(tdb, async (txDb) => runInOwnTransaction(txDb, async () => undefined)),
+    ).rejects.toThrow(InternalError);
+  });
+
+  test("a runner-bound personalDataGate (not declared on this TenantDb) still applies on the tx-bound db", async () => {
+    const denyEmail: PersonalDataGate = (_tableName, keys) => {
+      if (keys.includes("email")) {
+        throw new AccessDeniedError({ message: "personal data blocked" });
+      }
+    };
+    const tdb = createTenantDb(
+      testDb.db,
+      tenant1.tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { personalDataGate: denyEmail, unsafeRaw: { reason: "test: derive runner-bound gate" } },
+    );
+    // Mirrors createTenantDb(ctx.db.unsafeRaw(reason), ...): the gate now lives on the
+    // runner, not in this new TenantDb's own (unset) grants.
+    const gatedRunner = tdb.unsafeRaw("test: derive runner-bound gate");
+    const runnerBoundTdb = createTenantDb(gatedRunner, tenant1.tenantId);
+
+    expect(() =>
+      assertPersonalDataWrite(runnerBoundTdb, "run_in_own_tx_items", ["email"], entity),
+    ).toThrow(AccessDeniedError);
+
+    await runInOwnTransaction(runnerBoundTdb, async (txDb) => {
+      expect(() => assertPersonalDataWrite(txDb, "run_in_own_tx_items", ["email"], entity)).toThrow(
+        AccessDeniedError,
+      );
+    });
+  });
+});

package/src/db/index.ts

@@ -157,5 +157,6 @@ export {
   castTenantRows,
   createSystemDbView,
   createTenantDb,
+  runInOwnTransaction,
   SYSTEM_SCOPE_CHECK_BRAND,
 } from "./tenant-db";

package/src/db/query.ts

@@ -17,6 +17,7 @@ export {
   insertMany,
   insertOne,
   type OrderByClause,
+  runInNewTransaction,
   runInSavepoint,
   runInSavepointIfSupported,
   type SelectOptions,

package/src/db/tenant-db.ts

@@ -21,6 +21,7 @@ import {
   insertOne as bunInsertOne,
   selectMany as bunSelectMany,
   updateMany as bunUpdateMany,
+  runInNewTransaction,
   type SelectOptions,
   type WhereObject,
 } from "../db/query";
@@ -378,6 +379,25 @@ export function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: str
   return rebind(reason);
 }
 
+type OwnTransactionRunner = <T>(fn: (txDb: TenantDb) => Promise<T>) => Promise<T>;
+
+const ownTransactionRebinders = new WeakMap<TenantDb, OwnTransactionRunner>();
+
+export async function runInOwnTransaction<T>(
+  tenantDb: TenantDb,
+  fn: (txDb: TenantDb) => Promise<T>,
+): Promise<T> {
+  const rebind = ownTransactionRebinders.get(tenantDb);
+  if (!rebind) {
+    throw new InternalError({
+      message:
+        "runInOwnTransaction received a TenantDb not built by createTenantDb — " +
+        "no transaction rebinder bound.",
+    });
+  }
+  return rebind(fn);
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -685,6 +705,20 @@ export function createTenantDb(
     report("acknowledge-cross-tenant", reason);
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
+  ownTransactionRebinders.set(tenantDb, async (fn) => {
+    if (grants?.memberReadOnly) {
+      throw new InternalError({
+        message:
+          "runInOwnTransaction: memberReadOnly TenantDb — a fresh transaction would escape " +
+          "the enforced read-only scope.",
+      });
+    }
+    // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
+    const txGrants = personalDataGate ? { ...grants, personalDataGate } : grants;
+    return runInNewTransaction(db, (tx) =>
+      fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)),
+    );
+  });
   bindTenantDbRunner(tenantDb, db);
   if (personalDataGate) personalDataGates.set(tenantDb, personalDataGate);
   return tenantDb;

package/src/engine/__tests__/changeset-changes.test.ts

@@ -35,6 +35,15 @@ describe("parseChangesetChanges", () => {
     ]);
   });
 
+  test("keeps a blank line inside a multiline block as a paragraph break, not a truncation", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\nmigration: |\n  First paragraph.\n\n  Second paragraph after a blank line.\n-->`,
+      ".changeset/blank-line.md",
+    );
+
+    expect(changes[0]?.migration).toBe("First paragraph.\n\nSecond paragraph after a blank line.");
+  });
+
   test("rejects a breaking change without migration", () => {
     expect(() =>
       parseChangesetChanges(

package/src/engine/__tests__/entity-exclude-fields.integration.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { defineEntityUpdateHandler, defineEntityWriteHandler } from "../entity-handlers";
+import { createEntity, createTextField } from "../factories";
+
+const carEntity = createEntity({
+  table: "exclude_fields_cars",
+  fields: {
+    vin: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    model: createTextField({ personal: false, reason: "test_fixture" }),
+    internalNote: createTextField({ personal: false, reason: "test_fixture" }),
+  },
+});
+
+const carFeature = defineFeature("exclude-fields", (r) => {
+  r.crud("car", carEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    excludeFields: { create: ["internalNote"], update: ["vin"] },
+  });
+});
+
+const CREATE = "exclude-fields:write:car:create";
+const UPDATE = "exclude-fields:write:car:update";
+
+type WriteBody = {
+  readonly isSuccess: boolean;
+  readonly data?: { readonly data: Record<string, unknown> & { id: string; version: number } };
+  readonly error?: {
+    readonly code: string;
+    readonly details?: { readonly fields?: readonly { readonly path: string }[] };
+  };
+};
+
+describe("excludeFields on the generic create/update handlers", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [carFeature] });
+    await unsafeCreateEntityTable(stack.db, carEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "exclude_fields_cars"');
+  });
+
+  async function createCar(): Promise<{ id: string; version: number }> {
+    const res = await stack.http.write(CREATE, { vin: "WVW123", model: "Golf" }, TestUsers.user);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as WriteBody;
+    if (!body.data) throw new Error("create returned no data");
+    return body.data.data;
+  }
+
+  test("update rejects a payload that still carries an excluded field and keeps the row unchanged", async () => {
+    const car = await createCar();
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: car.id, version: car.version, changes: { vin: "HACKED", model: "Polo" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as WriteBody;
+    expect(body.error?.code).toBe("validation_error");
+    expect(body.error?.details?.fields?.map((field) => field.path)).toEqual(["changes.vin"]);
+
+    const rows = await asRawClient(stack.db).unsafe(
+      'SELECT vin, model FROM "exclude_fields_cars" WHERE id = $1',
+      [car.id],
+    );
+    expect(rows[0]).toMatchObject({ vin: "WVW123", model: "Golf" });
+  });
+
+  test("update without the excluded field writes the other fields", async () => {
+    const car = await createCar();
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: car.id, version: car.version, changes: { model: "Polo" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as WriteBody;
+    expect(body.data?.data).toMatchObject({ vin: "WVW123", model: "Polo" });
+  });
+
+  test("create honors its own exclusion list independently of update's", async () => {
+    const rejected = await stack.http.write(
+      CREATE,
+      { vin: "WVW999", internalNote: "set by client" },
+      TestUsers.user,
+    );
+    expect(rejected.status).toBe(400);
+    const body = (await rejected.json()) as WriteBody;
+    expect(body.error?.details?.fields?.map((field) => field.path)).toEqual(["internalNote"]);
+  });
+});
+
+describe("excludeFields definition-time checks", () => {
+  test("rejects an unknown field name", () => {
+    expect(() =>
+      defineEntityUpdateHandler("car", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["colour"],
+      }),
+    ).toThrow(/unknown field "colour"/);
+  });
+
+  test("rejects excluding a required field without default on create", () => {
+    expect(() =>
+      defineEntityWriteHandler("car:create", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["vin"],
+      }),
+    ).toThrow(/required without a default/);
+  });
+
+  test("rejects excludeFields on delete", () => {
+    expect(() =>
+      defineEntityWriteHandler("car:delete", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["model"],
+      }),
+    ).toThrow(/only applies to create and update/);
+  });
+});

package/src/engine/changeset-changes.ts

@@ -36,10 +36,23 @@ function parseBlock(raw: string, source: string): ReadonlyMap<string, string> {
     const value = match[2];
     if (value === "|") {
       const continuation: string[] = [];
-      while (index + 1 < lines.length && (lines[index + 1]?.startsWith("  ") ?? false)) {
-        index++;
-        const continuationLine = lines[index];
-        if (continuationLine) continuation.push(continuationLine.slice(2));
+      // A blank line inside the block is a paragraph break, not the end of it;
+      // stopping on the first one truncated the field and then threw a
+      // misleading "invalid line" error on the next indented line, which no
+      // longer looked like a `key: value` pair on its own.
+      while (index + 1 < lines.length) {
+        const next = lines[index + 1] ?? "";
+        if (next.startsWith("  ")) {
+          index++;
+          continuation.push(next.slice(2));
+          continue;
+        }
+        if (next.trim() === "") {
+          index++;
+          continuation.push("");
+          continue;
+        }
+        break;
       }
       fields.set(key, continuation.join("\n").trim());
       continue;

package/src/engine/entity-handlers.ts

@@ -29,6 +29,7 @@ import type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "./types/entity-handlers";
 
@@ -38,6 +39,7 @@ export type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "./types/entity-handlers";
 
@@ -202,10 +204,48 @@ function parseHandlerName<TVerb extends string>(
   return { entityName, verb: verbCandidate as TVerb }; // @cast-boundary engine-bridge
 }
 
+function isInTotalsMatchPair(entity: EntityDefinition, fieldName: string): boolean {
+  return Object.entries(entity.fields).some(
+    ([name, field]) =>
+      field.type === "embedded" &&
+      field.totalsMatch !== undefined &&
+      (name === fieldName || Object.values(field.totalsMatch).includes(fieldName)),
+  );
+}
+
+function assertExcludableFields(
+  name: string,
+  verb: (typeof WRITE_VERBS)[number],
+  entity: EntityDefinition,
+  excludedFields: readonly string[],
+): void {
+  if (excludedFields.length > 0 && verb !== "create" && verb !== "update") {
+    throw new Error(`"${name}": excludeFields only applies to create and update handlers.`);
+  }
+  for (const fieldName of excludedFields) {
+    const field = entity.fields[fieldName];
+    if (!field) {
+      throw new Error(`"${name}": excludeFields names unknown field "${fieldName}".`);
+    }
+    if (isInTotalsMatchPair(entity, fieldName)) {
+      throw new Error(
+        `"${name}": excludeFields cannot name "${fieldName}" — it is part of a totalsMatch pair, which must be written together.`,
+      );
+    }
+    const isRequired = "required" in field && field.required === true;
+    const hasDefault = "default" in field && field.default !== undefined;
+    if (verb === "create" && isRequired && !hasDefault) {
+      throw new Error(
+        `"${name}": excludeFields cannot name "${fieldName}" — it is required without a default, so no row could ever be created.`,
+      );
+    }
+  }
+}
+
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -213,6 +253,8 @@ export function defineEntityWriteHandler(
       `"${name}": restore is only valid for entities declared with softDelete: true.`,
     );
   }
+  const excludedFields = options.excludeFields ?? [];
+  assertExcludableFields(name, verb, entity, excludedFields);
 
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
@@ -263,7 +305,7 @@ export function defineEntityWriteHandler(
 
   switch (verb) {
     case "create":
-      schema = buildInsertSchema(entity);
+      schema = buildInsertSchema(entity, undefined, excludedFields);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
         // A caller-chosen id (deterministic-id idempotent creates) is only
@@ -284,7 +326,7 @@ export function defineEntityWriteHandler(
       schema = z.object({
         id: z.uuid(),
         version: z.number(),
-        changes: buildUpdateSchema(entity),
+        changes: buildUpdateSchema(entity, undefined, excludedFields),
       });
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
@@ -507,7 +549,7 @@ export function defineEntityQueryHandler(
 export function defineEntityCreateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:create`, entity, options);
 }
@@ -516,7 +558,7 @@ export function defineEntityCreateHandler(
 export function defineEntityUpdateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:update`, entity, options);
 }
@@ -651,11 +693,16 @@ export function registerEntityCrud(
     }
     return access;
   };
-  const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
-    ...writeOpts,
-    access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
-    description: options?.descriptions?.[verb] ?? writeOpts?.description,
-  });
+  const resolveWriteOpts = (verb: EntityCrudVerb): EntityWriteHandlerOptions => {
+    const excludeFields =
+      verb === "create" || verb === "update" ? options?.excludeFields?.[verb] : undefined;
+    return {
+      ...writeOpts,
+      access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
+      description: options?.descriptions?.[verb] ?? writeOpts?.description,
+      ...(excludeFields !== undefined && { excludeFields }),
+    };
+  };
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
     access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),

package/src/engine/schema-builder.ts

@@ -367,13 +367,25 @@ function applyTotalsMatchRefinements(
   return result;
 }
 
+// An excluded field stays in the shape as "must be absent" instead of being
+// dropped: zod strips unknown keys silently, so a client still sending it
+// would otherwise get a success without the write happening.
+function notWritableField(): z.ZodTypeAny {
+  return z.never().optional();
+}
+
 export function buildInsertSchema(
   entity: EntityDefinition,
   currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+  excludedFields: readonly string[] = [],
 ): z.ZodObject<Record<string, z.ZodTypeAny>> {
   const shape: Record<string, z.ZodTypeAny> = {};
 
   for (const [name, field] of Object.entries(entity.fields)) {
+    if (excludedFields.includes(name)) {
+      shape[name] = notWritableField();
+      continue;
+    }
     const zodField = fieldToZod(field, currencies);
     const hasDefault = "default" in field && field.default !== undefined;
     const isRequired = "required" in field && field.required === true;
@@ -392,10 +404,15 @@ export function buildInsertSchema(
 export function buildUpdateSchema(
   entity: EntityDefinition,
   currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+  excludedFields: readonly string[] = [],
 ): z.ZodObject<Record<string, z.ZodTypeAny>> {
   const shape: Record<string, z.ZodTypeAny> = {};
 
   for (const [name, field] of Object.entries(entity.fields)) {
+    if (excludedFields.includes(name)) {
+      shape[name] = notWritableField();
+      continue;
+    }
     // Update schemas never apply defaults for OMITTED fields — a user that
     // sends only `{ title }` means "only change title"; zod defaults would
     // silently inject default values for every omitted field and clobber

package/src/engine/types/index.ts

@@ -63,6 +63,7 @@ export type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "@cosmicdrift/kumiko-types/entity-handlers";
 // Cross-Feature Compile-Time-Type-Map — features extend per declare-module.

package/src/files/__tests__/files.integration.test.ts

@@ -66,6 +66,7 @@ const testTenantEntity = createEntity({
   fields: {
     name: createTextField({ personal: false, reason: "test_fixture", required: true }),
     logo: createImageField({ maxSize: "2mb", accept: ["png", "jpg"] }),
+    strictLogo: createImageField({ maxSize: "2mb", accept: ["jpg"] }),
     importFile: createFileField({ maxSize: "2mb", accept: ["csv"] }),
   },
 });
@@ -266,8 +267,8 @@ describe("file validation", () => {
   });
 
   test("validateFileContent accepts .doc/.docx bytes matching their declared extension", () => {
-    expect(validateFileContent("report.doc", docBytes)).toBeNull();
-    expect(validateFileContent("report.docx", docxBytes)).toBeNull();
+    expect(validateFileContent("report.doc", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("report.docx", docxBytes)).toEqual({ kind: "ok" });
   });
 
   test("validateFileContent rejects .doc/.docx whose content doesn't match the extension", () => {
@@ -275,13 +276,15 @@ describe("file validation", () => {
       "fake.doc",
       new TextEncoder().encode("not actually a Word document, just text"),
     );
-    expectErrorIncludes(fakeDoc, "content_mismatch");
+    expect(fakeDoc.kind).toBe("rejected");
+    expectErrorIncludes(fakeDoc.kind === "rejected" ? fakeDoc.error : null, "content_mismatch");
 
     const fakeDocx = validateFileContent(
       "fake.docx",
       new TextEncoder().encode("not actually a docx, just text"),
     );
-    expectErrorIncludes(fakeDocx, "content_mismatch");
+    expect(fakeDocx.kind).toBe("rejected");
+    expectErrorIncludes(fakeDocx.kind === "rejected" ? fakeDocx.error : null, "content_mismatch");
   });
 
   test("validateFileContent now content-verifies every signature-bearing extension (e.g. pdf), not just doc/docx", () => {
@@ -289,23 +292,73 @@ describe("file validation", () => {
       "fake.pdf",
       new TextEncoder().encode("not a PDF at all, just text"),
     );
-    expectErrorIncludes(mismatch, "content_mismatch");
+    expect(mismatch.kind).toBe("rejected");
+    expectErrorIncludes(mismatch.kind === "rejected" ? mismatch.error : null, "content_mismatch");
   });
 
   test("validateFileContent leaves extensions without a magic-byte signature unchecked (csv/txt/svg/md/json/unknown)", () => {
     const text = new TextEncoder().encode("just plain text, not any binary format");
-    expect(validateFileContent("data.csv", text)).toBeNull();
-    expect(validateFileContent("notes.txt", text)).toBeNull();
-    expect(validateFileContent("readme.md", text)).toBeNull();
-    expect(validateFileContent("data.json", text)).toBeNull();
-    expect(validateFileContent("logo.svg", text)).toBeNull();
-    expect(validateFileContent("file.unknownext", text)).toBeNull();
+    expect(validateFileContent("data.csv", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("notes.txt", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("readme.md", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("data.json", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("logo.svg", text)).toEqual({ kind: "ok" });
+    expect(validateFileContent("file.unknownext", text)).toEqual({ kind: "ok" });
   });
 
   test("validateFileContent treats a prototype-property extension as unknown instead of crashing", () => {
-    expect(validateFileContent("evil.constructor", docBytes)).toBeNull();
-    expect(validateFileContent("evil.__proto__", docBytes)).toBeNull();
-    expect(validateFileContent("evil.toString", docBytes)).toBeNull();
+    expect(validateFileContent("evil.constructor", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("evil.__proto__", docBytes)).toEqual({ kind: "ok" });
+    expect(validateFileContent("evil.toString", docBytes)).toEqual({ kind: "ok" });
+  });
+
+  const pngBytesForNormalization = new Uint8Array([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    ...Array(20).fill(0),
+  ]);
+
+  test("validateFileContent normalizes PNG bytes uploaded as .jpg when png is in accept", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization, ["jpg", "png"])).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
+  });
+
+  test("validateFileContent still rejects PNG bytes uploaded as .jpg when png is not in accept", () => {
+    const result = validateFileContent("photo.jpg", pngBytesForNormalization, ["jpg"]);
+    expect(result.kind).toBe("rejected");
+  });
+
+  test("validateFileContent rejects a format not covered by accept at all, even with accept present", () => {
+    const result = validateFileContent("photo.jpg", new TextEncoder().encode("%PDF-1.4 minimal"), [
+      "jpg",
+      "png",
+    ]);
+    expect(result.kind).toBe("rejected");
+  });
+
+  test("validateFileContent without an accept list normalizes too — no accept means no restriction to widen", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization)).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
+  });
+
+  test("validateFileContent with an empty accept list normalizes the same as no accept at all", () => {
+    expect(validateFileContent("photo.jpg", pngBytesForNormalization, [])).toEqual({
+      kind: "normalized",
+      extension: "png",
+      mimeType: "image/png",
+    });
   });
 
   test("validateFile with accept: ['constructor'] and a matching filename never throws", () => {
@@ -667,7 +720,7 @@ describe("content_mismatch is enforced by filename extension for every signature
   ]);
   const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(20).fill(0)]);
 
-  test("PDF bytes uploaded as x.jpg against an accept: [jpg] field are rejected with content_mismatch", async () => {
+  test("PDF bytes uploaded as x.jpg against an accept: [png, jpg] field are rejected with content_mismatch", async () => {
     const res = await uploadFile(adminUser, "x.jpg", pdfBytes, "image/jpeg", {
       entityType: "tenant",
       entityId: "1",
@@ -678,6 +731,44 @@ describe("content_mismatch is enforced by filename extension for every signature
     expect(body.error).toContain("content_mismatch");
   });
 
+  test("PNG bytes uploaded as x.jpg are normalized and stored as image/png when png is in the field's accept", async () => {
+    const res = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.fileName).toBe("x.jpg");
+    expect(body.mimeType).toBe("image/png");
+    expect(body.storageKey).toMatch(/\.png$/);
+  });
+
+  test("PNG bytes normalized on upload are served back with the matching image/png Content-Type", async () => {
+    const uploadRes = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+  });
+
+  test("PNG bytes uploaded as x.jpg against a field whose accept doesn't include png are still rejected with content_mismatch", async () => {
+    const res = await uploadFile(adminUser, "x.jpg", pngBytes, "image/jpeg", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "strictLogo",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("content_mismatch");
+  });
+
   test("real signature bytes with a matching extension upload successfully", async () => {
     for (const [fileName, bytes, mimeType] of [
       ["real.jpg", jpegBytes, "image/jpeg"],
@@ -710,6 +801,15 @@ describe("content_mismatch is enforced by filename extension for every signature
     expect(protoRes.status).toBe(201);
   });
 
+  test("an unattached upload (no entityType/fieldName, so no accept restriction) also normalizes mislabeled bytes", async () => {
+    const res = await uploadFile(adminUser, "vin.jpg", pngBytes, "image/jpeg");
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.fileName).toBe("vin.jpg");
+    expect(body.mimeType).toBe("image/png");
+    expect(body.storageKey).toMatch(/\.png$/);
+  });
+
   test("a too-short .png upload (fewer bytes than the PNG signature) is rejected with content_mismatch", async () => {
     // A zero-byte file part is dropped by Bun's multipart parser before it
     // ever reaches the route handler as `file`, so this uses one byte

package/src/files/file-routes.ts

@@ -224,6 +224,27 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       return c.json({ error: validationError }, 400);
     }
 
+    const data = new Uint8Array(await file.arrayBuffer());
+
+    const contentValidation = validateFileContent(file.name, data, accept);
+    if (contentValidation.kind === "rejected") {
+      return c.json({ error: contentValidation.error }, 400);
+    }
+
+    // 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.
+    let mimeType: string;
+    if (contentValidation.kind === "normalized") {
+      mimeType = contentValidation.mimeType;
+    } else {
+      const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
+      if (mimeTypeResolution.kind === "rejected") {
+        return c.json({ error: mimeTypeResolution.error }, 400);
+      }
+      mimeType = mimeTypeResolution.mimeType;
+    }
+
     const fileRefId = generateId();
     const storageKey = buildStorageKey(
       user.tenantId,
@@ -232,21 +253,9 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       fieldName ?? "file",
       file.name,
       generateId(),
+      contentValidation.kind === "normalized" ? contentValidation.extension : undefined,
     );
 
-    const data = new Uint8Array(await file.arrayBuffer());
-
-    const contentValidationError = validateFileContent(file.name, data);
-    if (contentValidationError) {
-      return c.json({ error: contentValidationError }, 400);
-    }
-
-    const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
-    if (mimeTypeResolution.kind === "rejected") {
-      return c.json({ error: mimeTypeResolution.error }, 400);
-    }
-    const mimeType = mimeTypeResolution.mimeType;
-
     // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
     // inside a PG connection's tx window). On DB-tx rollback below the bytes
     // are orphaned in the provider; cleanup-jobs sweep those later. Losing a

package/src/files/index.ts

@@ -33,6 +33,7 @@ export {
   transferTenantStorageUsage,
 } from "./storage-tracking";
 export type {
+  FileContentValidationResult,
   FileMetadata,
   FileStorageProvider,
   FileValidationOptions,

package/src/files/types.ts

@@ -79,6 +79,15 @@ function lookupExtensionWhitelist(ext: string): readonly string[] | undefined {
   return EXTENSION_MIME_WHITELIST[ext];
 }
 
+// Reverse of lookupExtensionWhitelist: every extension whose whitelist entry
+// includes this MIME type (e.g. "image/jpeg" -> ["jpg", "jpeg"]) — backs
+// validateFileContent's accept-based normalization below.
+function extensionsForMimeType(mimeType: string): readonly string[] {
+  return Object.entries(EXTENSION_MIME_WHITELIST)
+    .filter(([, mimeTypes]) => mimeTypes.includes(mimeType))
+    .map(([ext]) => ext);
+}
+
 // Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
 // a reliable binary signature. Used both at upload time (validateFileContent)
 // and at serve time (resolveServedContentType) — never trust the stored/
@@ -217,17 +226,48 @@ function signatureMimeTypesForExtension(ext: string): readonly string[] {
   );
 }
 
+export type FileContentValidationResult =
+  | { readonly kind: "ok" }
+  | { readonly kind: "normalized"; readonly extension: string; readonly mimeType: string }
+  | { readonly kind: "rejected"; readonly error: string };
+
 // Separate from validateFile: metadata is known before the upload body is
 // fully read, content-verification only after — callers reject early on
 // metadata without buffering bytes they'll then have to reject anyway.
-export function validateFileContent(fileName: string, content: Uint8Array): string | null {
+//
+// When the sniffed signature doesn't match the declared extension but the
+// sniffed type's OWN extension is in a non-empty `accept`, the upload
+// normalizes to that type instead of being rejected — this only widens which
+// of the field's own allowed formats a mislabeled upload can settle into,
+// never which formats are accepted. With no `accept` restriction at all
+// (undefined or empty, same "unrestricted" meaning validateFile gives it),
+// any recognized signature normalizes the same way, since there is no
+// declared list left to widen.
+export function validateFileContent(
+  fileName: string,
+  content: Uint8Array,
+  accept?: readonly string[],
+): FileContentValidationResult {
   const ext = extractExtension(fileName);
-  if (!ext) return null;
+  if (!ext) return { kind: "ok" };
   const signatureMimeTypes = signatureMimeTypesForExtension(ext);
-  if (signatureMimeTypes.length === 0) return null;
+  if (signatureMimeTypes.length === 0) return { kind: "ok" };
   const sniffed = sniffMimeType(content);
-  if (sniffed && signatureMimeTypes.includes(sniffed)) return null;
-  return `content_mismatch: ".${ext}" upload bytes are ${sniffed ?? "unrecognized"}, expected ${signatureMimeTypes.join(" or ")}`;
+  if (sniffed && signatureMimeTypes.includes(sniffed)) return { kind: "ok" };
+  if (sniffed) {
+    const candidateExtensions = extensionsForMimeType(sniffed);
+    const hasAcceptRestriction = accept !== undefined && accept.length > 0;
+    const normalizedExtension = hasAcceptRestriction
+      ? candidateExtensions.find((candidate) => accept.includes(candidate))
+      : candidateExtensions[0];
+    if (normalizedExtension) {
+      return { kind: "normalized", extension: normalizedExtension, mimeType: sniffed };
+    }
+  }
+  return {
+    kind: "rejected",
+    error: `content_mismatch: ".${ext}" upload bytes are ${sniffed ?? "unrecognized"}, expected ${signatureMimeTypes.join(" or ")}`,
+  };
 }
 
 export type UploadMimeTypeResolution =
@@ -270,8 +310,12 @@ export function buildStorageKey(
   fieldName: string,
   fileName: string,
   uniqueId: string,
+  // Set when validateFileContent normalized the upload to a different real
+  // type — the storage key then reflects the sniffed type, not the user's
+  // (wrong) original extension.
+  extensionOverride?: string,
 ): string {
-  const rawExt = fileName.split(".").pop() ?? "";
+  const rawExt = extensionOverride ?? fileName.split(".").pop() ?? "";
   const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
   return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
 }

package/src/ui-types/formality.ts

@@ -0,0 +1,7 @@
+export type Formality = "formal" | "informal";
+
+// BCP-47 private-use subtag: a translation bundle keyed "de-x-formal" holds the
+// formal ("Sie") wording and only needs the keys that differ from plain "de".
+export function formalLocaleTag<Locale extends string>(locale: Locale): `${Locale}-x-formal` {
+  return `${locale}-x-formal`;
+}

package/src/ui-types/index.ts

@@ -137,6 +137,7 @@ export type {
   QualifiedContentCollection,
   WorkspaceSchema,
 } from "./app-schema";
+export { type Formality, formalLocaleTag } from "./formality";
 export type {
   ListRowMetaColumnType,
   ListRowMetaReference,