feat(codegen-ts): typed <Entity>Patch surface for the update path (FR-035, #198)

The generated `update<Entity>` took `data: unknown` and validated with
`InsertSchema.partial()`. It worked, but gave adopters zero compile-time safety —
a renamed or dropped field in an update call was silently accepted and silently
not written. #198's hand-written single-column setters exist partly to regain that
safety.

Now:
  - zod-validators emits `export type <Entity>Patch = z.input<typeof <Entity>UpdateSchema>`
    — every settable field, optional.
  - renderUpdateFn takes `patch: <Entity>Patch` (was `data: unknown`) and validates
    with the purpose-built `<Entity>UpdateSchema` — the SAME schema the routes tier
    already uses — instead of `InsertSchema.partial()`. A renamed/dropped field is now
    a TS compile error at every `update<Entity>` call site (the #198 compile-safety
    property); `.set()` still writes only the assigned columns, so an omitted field is
    untouched (PATCH-1).
  - empty-patch guard (PATCH-5): an empty patch returns the current row rather than
    letting Drizzle throw on an empty SET clause.

The AGENT-API.md generator's documented `update` signature tracks the new
`patch: <Entity>Patch` shape (the api-docs-accuracy gate compiles the doc's worked
example against the real generated code). The consumer-compile test's `zod` stub gains
the `z.input`/`infer`/`output` type-namespace helpers — the generated code compiles
cleanly against real zod (verified), the stub just hadn't modeled that helper.

Naming: the function keeps its shipped name `update<Entity>` — the cross-port contract
is the PATCH semantics, not the identifier; renaming would churn every adopter for zero
behavior change (ports that ship a partial method alongside a full-row one name it
`patch`).

All 44 query goldens regenerated (verified: only the Patch import/param/type + the
empty-patch guard changed). codegen-ts typecheck clean; api-docs accuracy 27/27;
consumer-compile 9/9; TS api-contract both lanes 44/44 (incl. the omitted-field-survives
forcing function from 7fab436).

Part of FR-035. C# (7fab436) and Kotlin (ad632ac) already ship their patch surface;
Python + Java typed-patch shapes follow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hd5NWZ1rKau63vJzrBSpLb

Author: dmealing

server/typescript/packages/codegen-ts/src/generators/api-model.ts

@@ -506,11 +506,11 @@ function dataAccessSymbols(
       name: update,
       kind: "data-access",
       importPath: mod,
-      signature: `${update}(db: Db, ${pk}: ${pkType}, data: unknown): Promise<${name} | null>`,
-      params: [`db: Db`, `${pk}: ${pkType}`, `data: unknown`],
+      signature: `${update}(db: Db, ${pk}: ${pkType}, patch: ${name}Patch): Promise<${name} | null>`,
+      params: [`db: Db`, `${pk}: ${pkType}`, `patch: ${name}Patch`],
       returns: `Promise<${name} | null>`,
-      throws: `ZodError when data fails the partial ${name}InsertSchema validation.`,
-      usage: `Partially update an existing ${name} by primary key; null when not found.`,
+      throws: `ZodError when the patch fails ${name}UpdateSchema validation.`,
+      usage: `Partially update a ${name} by primary key — writes only the assigned fields; null when not found. A renamed/dropped field is a compile error.`,
       fields: updateShape,
     },
     {

server/typescript/packages/codegen-ts/src/templates/queries-file.ts

@@ -80,7 +80,7 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [

server/typescript/packages/codegen-ts/src/templates/queries.ts

@@ -91,12 +91,23 @@ export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
   const fnName = updateFnName(entityName);
-  const schemaName = `${entityName}InsertSchema`;
+  const findByIdFn = findByIdFnName(entityName);
+  // PATCH contract (FR-035): validate the caller's assignments against the
+  // UPDATE schema (all-optional, PK/@readOnly excluded, no insert-time transforms
+  // like @autoSet-onCreate → now() or the InsertSchema's discriminator handling)
+  // — NOT `InsertSchema.partial()`. The typed `<Entity>Patch` param makes a
+  // renamed/dropped field a compile error at every call site (PATCH-1..4);
+  // `.set()` writes ONLY the assigned columns, so an omitted field is untouched.
+  const updateSchemaName = `${entityName}UpdateSchema`;
+  const patchType = `${entityName}Patch`;
   const eqSym = imp("eq@drizzle-orm");
 
   return code`
-export async function ${fnName}(db: Db, ${pkField}: ${pkType}, data: unknown): Promise<${entityName} | null> {
-  const validated = ${schemaName}.partial().parse(data);
+export async function ${fnName}(db: Db, ${pkField}: ${pkType}, patch: ${patchType}): Promise<${entityName} | null> {
+  const validated = ${updateSchemaName}.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current row rather than let
+  // Drizzle throw on an empty SET clause.
+  if (Object.keys(validated).length === 0) return ${findByIdFn}(db, ${pkField});
   const [${singularVar}] = await db.update(${varName}).set(validated).where(${eqSym}(${varName}.${pkField}, ${pkField})).returning();
   return ${singularVar} ?? null;
 }

server/typescript/packages/codegen-ts/src/templates/zod-validators.ts

@@ -325,6 +325,10 @@ ${joinCode(insertFieldLines, { on: ",\n" })}
 ${docsPrefix}export const ${updateSchemaName} = ${z}.object({
 ${joinCode(updateFieldLines, { on: ",\n" })}
 });
+
+/** Typed patch shape for ${obj.name}: every settable field, optional (FR-035 PATCH). A
+ * renamed/dropped field is a compile error at every \`update${obj.name}\` call site. */
+export type ${obj.name}Patch = ${z}.input<typeof ${updateSchemaName}>;
 `;
 }
 

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/Tag.queries.ts

@@ -6,7 +6,13 @@ import { eq, inArray } from "drizzle-orm";
 import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
 type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;
 
-import { type Tag, TagInsertSchema, tags } from "./Tag";
+import {
+  type Tag,
+  TagInsertSchema,
+  type TagPatch,
+  tags,
+  TagUpdateSchema,
+} from "./Tag";
 export async function findTagById(db: Db, id: number): Promise<Tag | null> {
   const [tag] = await db.select().from(tags).where(eq(tags.id, id)).limit(1);
   return tag ?? null;
@@ -32,9 +38,14 @@ export async function createTag(db: Db, data: unknown): Promise<Tag> {
 export async function updateTag(
   db: Db,
   id: number,
-  data: unknown,
+  patch: TagPatch,
 ): Promise<Tag | null> {
-  const validated = TagInsertSchema.partial().parse(data);
+  const validated = TagUpdateSchema.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current row rather than let
+  // Drizzle throw on an empty SET clause.
+  if (Object.keys(validated).length === 0) {
+    return findTagById(db, id);
+  }
   const [tag] = await db
     .update(tags)
     .set(validated)

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/Tag.ts

@@ -40,6 +40,10 @@ export const TagUpdateSchema = z.object({
   label: z.string().min(1).max(100).optional(),
   customerId: z.number().int().optional(),
 });
+
+/** Typed patch shape for Tag: every settable field, optional (FR-035 PATCH). A
+ * renamed/dropped field is a compile error at every `updateTag` call site. */
+export type TagPatch = z.input<typeof TagUpdateSchema>;
 /**
  * Metadata constants for Tag.
  *

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/shop/commerce/Order.queries.ts

@@ -6,7 +6,13 @@ import { eq, inArray } from "drizzle-orm";
 import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
 type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;
 
-import { type Order, OrderInsertSchema, orders } from "./Order";
+import {
+  type Order,
+  OrderInsertSchema,
+  type OrderPatch,
+  orders,
+  OrderUpdateSchema,
+} from "./Order";
 export async function findOrderById(db: Db, id: number): Promise<Order | null> {
   const [order] = await db
     .select()
@@ -36,9 +42,14 @@ export async function createOrder(db: Db, data: unknown): Promise<Order> {
 export async function updateOrder(
   db: Db,
   id: number,
-  data: unknown,
+  patch: OrderPatch,
 ): Promise<Order | null> {
-  const validated = OrderInsertSchema.partial().parse(data);
+  const validated = OrderUpdateSchema.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current row rather than let
+  // Drizzle throw on an empty SET clause.
+  if (Object.keys(validated).length === 0) {
+    return findOrderById(db, id);
+  }
   const [order] = await db
     .update(orders)
     .set(validated)

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/shop/commerce/Order.ts

@@ -49,6 +49,10 @@ export const OrderUpdateSchema = z.object({
   productId: z.number().int().optional(),
   quantity: z.number().int().optional(),
 });
+
+/** Typed patch shape for Order: every settable field, optional (FR-035 PATCH). A
+ * renamed/dropped field is a compile error at every `updateOrder` call site. */
+export type OrderPatch = z.input<typeof OrderUpdateSchema>;
 /**
  * Metadata constants for Order.
  *

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/shop/commerce/Product.queries.ts

@@ -6,7 +6,13 @@ import { eq, inArray } from "drizzle-orm";
 import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
 type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;
 
-import { type Product, ProductInsertSchema, products } from "./Product";
+import {
+  type Product,
+  ProductInsertSchema,
+  type ProductPatch,
+  products,
+  ProductUpdateSchema,
+} from "./Product";
 export async function findProductById(
   db: Db,
   id: number,
@@ -39,9 +45,14 @@ export async function createProduct(db: Db, data: unknown): Promise<Product> {
 export async function updateProduct(
   db: Db,
   id: number,
-  data: unknown,
+  patch: ProductPatch,
 ): Promise<Product | null> {
-  const validated = ProductInsertSchema.partial().parse(data);
+  const validated = ProductUpdateSchema.parse(patch);
+  // PATCH-5: an empty patch is a no-op — return the current row rather than let
+  // Drizzle throw on an empty SET clause.
+  if (Object.keys(validated).length === 0) {
+    return findProductById(db, id);
+  }
   const [product] = await db
     .update(products)
     .set(validated)

server/typescript/packages/codegen-ts/test/golden/__snapshots__/package/shop/commerce/Product.ts

@@ -37,6 +37,10 @@ export const ProductUpdateSchema = z.object({
   name: z.string().min(1).max(200).optional(),
   tagId: z.number().int().optional(),
 });
+
+/** Typed patch shape for Product: every settable field, optional (FR-035 PATCH). A
+ * renamed/dropped field is a compile error at every `updateProduct` call site. */
+export type ProductPatch = z.input<typeof ProductUpdateSchema>;
 /**
  * Metadata constants for Product.
  *