feat(#203): TS insertPreserving escape hatch (@autoset verbatim insert)

Closes the one TS gap in #203's cross-port @autoset stamping: the
insertPreserving escape hatch (Python/C#/Java/Kotlin already emit it). For an
entity that declares @autoset fields, codegen-ts now emits an additional
`<Entity>InsertPreservingSchema` (the @autoset timestamp columns validated
VERBATIM — no create-time now() transform) plus an
`insertPreserving<Entity>(db, data)` query that persists the caller's original
timestamps unchanged. The import / restore / replication path; the normal
`create<Entity>` still stamps now() (created == updated). Both the schema and
the function are emitted ONLY for @autoset entities — a plain entity is
byte-identical to before (no fixture declares @autoset, so no golden changes).

The emit predicate (hasAutoSetFields) is shared across the schema emission, the
per-field preserving line, and the queries-file import+fn, so a queries file can
never import a preserving schema that wasn't emitted. The preserving schema's
@autoset columns use the field's natural zod expr, so a @required onCreate
column is required (you supply the value you're preserving) and a non-required
onUpdate column is optional (Drizzle's $defaultFn fills now() if omitted).

Verified: codegen-ts 946 pass / 0 fail (incl. new auto-set-insert-preserving
test, 8 cases); typecheck exit 0; rendered Event output eyeballed. Known
follow-up for the coordinated gate: a TPH base/subtype with @autoset takes a
non-vanilla queries path, so its preserving schema would be a dead export —
folded into the TPH-parity reconciliation.

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

Author: dmealing

server/typescript/packages/codegen-ts/src/naming.ts

@@ -111,6 +111,13 @@ export function createFnName(entityName: string): string {
   return `create${entityName}`;
 }
 
+/** Generated insert-preserving helper name: `insertPreserving<Entity>` (#203 —
+ *  the import/restore/replication escape hatch that writes @autoSet columns
+ *  verbatim). Emitted only for entities that declare @autoSet fields. */
+export function insertPreservingFnName(entityName: string): string {
+  return `insertPreserving${entityName}`;
+}
+
 /** Generated update helper name: `update<Entity>`. */
 export function updateFnName(entityName: string): string {
   return `update${entityName}`;

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

@@ -13,6 +13,7 @@ import {
   renderFindByIdFn,
   renderListFn,
   renderCreateFn,
+  renderInsertPreservingFn,
   renderUpdateFn,
   renderDeleteByIdFn,
   renderReverseFinderFns,
@@ -23,6 +24,7 @@ import { pluralize, findByIdFnName, listFnName } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isTphDiscriminatorBase, tphConcreteSubtypes } from "./tph-discriminator.js";
 import { isProjection } from "../projection/projection-detector.js";
+import { hasAutoSetFields } from "./zod-validators.js";
 
 export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
   // FR-017 Tier 2 — a TPH discriminator base gets a polymorphic queries file:
@@ -74,20 +76,26 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
       // (the most common SQLite driver) with "is not assignable".
       : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
 
+  // #203 — an @autoSet entity additionally imports its preserving-shape schema
+  // and emits the `insertPreserving<Entity>` escape hatch after `create<Entity>`.
+  const autoSet = hasAutoSetFields(obj);
+  const preservingImport = autoSet ? `, ${entityName}InsertPreservingSchema` : "";
+
   // Literal imports (Db type + entity types) live in a code block so they sort
   // alongside ts-poet's hoisted imp() imports at the top of the body.
   const literalImports = code`
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema${preservingImport}, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [
     literalImports,
     renderFindByIdFn(obj, ctx),
     renderListFn(obj, ctx),
     renderCreateFn(obj, ctx),
+    ...(autoSet ? [renderInsertPreservingFn(obj, ctx)] : []),
     renderUpdateFn(obj, ctx),
     renderDeleteByIdFn(obj, ctx),
   ];

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

@@ -9,6 +9,7 @@ import {
   findByIdFnName,
   listFnName,
   createFnName,
+  insertPreservingFnName,
   updateFnName,
   deleteByIdFnName,
   reverseFinderFnName,
@@ -85,6 +86,31 @@ export async function ${fnName}(db: Db, data: unknown): Promise<${entityName}> {
 `;
 }
 
+/**
+ * #203 — the `insertPreserving<Entity>` escape hatch. Cross-port with the Java /
+ * Kotlin / C# / Python ports: emitted ONLY for an entity that declares @autoSet
+ * fields, it persists the row WITHOUT the create-time now() stamp — the @autoSet
+ * columns are written verbatim from the caller's data — for import / restore /
+ * replication paths that must keep the original timestamps. It validates through
+ * `<Entity>InsertPreservingSchema` (the preserving-shape schema whose @autoSet
+ * columns carry no transform); the normal `create<Entity>` always stamps now().
+ */
+export function renderInsertPreservingFn(entity: MetaObject, ctx: RenderContext): Code {
+  const varName = ctx.collectionName(entity.name);
+  const entityName = entity.name;
+  const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+  const fnName = insertPreservingFnName(entityName);
+  const schemaName = `${entityName}InsertPreservingSchema`;
+
+  return code`
+export async function ${fnName}(db: Db, data: unknown): Promise<${entityName}> {
+  const validated = ${schemaName}.parse(data);
+  const [${singularVar}] = await db.insert(${varName}).values(validated).returning();
+  return ${singularVar}!;
+}
+`;
+}
+
 export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const varName = ctx.collectionName(entity.name);
   const entityName = entity.name;

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

@@ -73,6 +73,19 @@ export function isTphSubtype(obj: MetaObject): boolean {
   return tphDiscriminatorPin(obj) !== undefined;
 }
 
+/** True when this object declares at least one @autoSet timestamp field
+ *  (onCreate or onUpdate). Drives whether codegen emits the #203
+ *  `<Entity>InsertPreservingSchema` + `insertPreserving<Entity>` escape hatch —
+ *  a plain entity has nothing to preserve, so both are omitted. Resolving
+ *  (ADR-0039): honors an @autoSet inherited via extends. */
+export function hasAutoSetFields(obj: MetaObject): boolean {
+  for (const child of obj.fields()) {
+    const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
+    if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) return true;
+  }
+  return false;
+}
+
 /**
  * FR-017 Tier 2 — the per-subtype FULL read schema `<Sub>Schema`. Unlike the
  * insert schema, this includes every effective field (PK included) so a raw DB
@@ -282,6 +295,11 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
 
   const insertFieldLines: Code[] = [];
   const updateFieldLines: Code[] = [];
+  // #203 — the `insertPreserving` escape hatch's schema: same shape as the insert
+  // schema, but @autoSet columns are written VERBATIM (no create-time now()
+  // transform). Only emitted when the entity declares @autoSet fields.
+  const preservingFieldLines: Code[] = [];
+  const emitPreserving = hasAutoSetFields(obj);
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
     // FR-013: @readOnly fields appear in neither InsertSchema nor UpdateSchema.
@@ -295,9 +313,9 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
     // path) — the app never writes it via the body and never updates it.
     // Insert: pinned literal. Update: omitted entirely (clients can't change subtype).
     if (tphPin !== undefined && child.name === tphPin.fieldName) {
-      insertFieldLines.push(
-        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
-      );
+      const litLine = code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`;
+      insertFieldLines.push(litLine);
+      preservingFieldLines.push(litLine);
       continue;
     }
 
@@ -308,8 +326,13 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
       insertFieldLines.push(
         code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
+      // Preserving schema: the @autoSet column is validated verbatim (its natural
+      // field expr) so an import/restore keeps the caller's original timestamp.
+      preservingFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`);
     } else {
-      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`);
+      const fieldLine = code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`;
+      insertFieldLines.push(fieldLine);
+      preservingFieldLines.push(fieldLine);
     }
 
     // Update schema: @autoSet onCreate → omit entirely; onUpdate → transform
@@ -339,10 +362,24 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
 
   const insertSchemaName = `${obj.name}InsertSchema`;
   const updateSchemaName = `${obj.name}UpdateSchema`;
+  const preservingSchemaName = `${obj.name}InsertPreservingSchema`;
 
   const docs = renderDocsFor(obj);
   const docsPrefix = docs ? `${docs}\n` : "";
 
+  // #203 — emit the preserving insert-shape only for @autoSet entities (nothing to
+  // preserve otherwise). Backs `insertPreserving<Entity>` (import/restore/replication).
+  const preservingBlock = emitPreserving
+    ? code`
+
+/** Insert-shape for import / restore / replication of ${obj.name}: identical to
+ * ${insertSchemaName}, but the @autoSet timestamp columns are written VERBATIM
+ * (no create-time now() stamp) so the caller's original values are preserved. */
+export const ${preservingSchemaName} = ${z}.object({
+${joinCode(preservingFieldLines, { on: ",\n" })}
+});`
+    : code``;
+
   return code`
 ${docsPrefix}export const ${insertSchemaName} = ${z}.object({
 ${joinCode(insertFieldLines, { on: ",\n" })}
@@ -354,7 +391,7 @@ ${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}>;
+export type ${obj.name}Patch = ${z}.input<typeof ${updateSchemaName}>;${preservingBlock}
 `;
 }
 

server/typescript/packages/codegen-ts/test/templates/auto-set-insert-preserving.test.ts

@@ -0,0 +1,126 @@
+// Issue #203 — the `insertPreserving` escape hatch (TS parity with the other 4 ports).
+//
+// For an entity that declares @autoSet fields, codegen emits an additional
+// `<Entity>InsertPreservingSchema` (the @autoSet columns validated VERBATIM, WITHOUT
+// the create-time `now()` transform) plus an `insertPreserving<Entity>(db, data)`
+// query — the import / restore / replication path that keeps the original timestamps.
+// Emitted ONLY when the entity has @autoSet fields; a plain entity is byte-identical.
+
+import { describe, test, expect } from "bun:test";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { TypeId, TYPE_IDENTITY,
+         FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_TIMESTAMP,
+         IDENTITY_SUBTYPE_PRIMARY, OBJECT_SUBTYPE_ENTITY } from "@metaobjectsdev/metadata";
+import { meta, metaRoot, metaObject, metaField } from "../_meta-build.js";
+import { renderZodValidators, hasAutoSetFields } from "../../src/templates/zod-validators.js";
+import { renderInsertPreservingFn } from "../../src/templates/queries.js";
+import { renderQueriesFile } from "../../src/templates/queries-file.js";
+import { makeRenderContext } from "../../src/render-context.js";
+import { buildPkMap } from "../../src/pk-resolver.js";
+import { buildRelationMap } from "../../src/relation-resolver.js";
+
+/** Entity WITH @autoSet fields (createdAt onCreate + updatedAt onUpdate). */
+function makeAutoSetEntity(): MetaObject {
+  const entity = metaObject(OBJECT_SUBTYPE_ENTITY, "Event");
+  const id = metaField(FIELD_SUBTYPE_LONG, "id");
+  entity.addChild(id);
+  const name = metaField(FIELD_SUBTYPE_STRING, "name");
+  name.setAttr("required", true);
+  entity.addChild(name);
+  const createdAt = metaField(FIELD_SUBTYPE_TIMESTAMP, "createdAt");
+  createdAt.setAttr("autoSet", "onCreate");
+  entity.addChild(createdAt);
+  const updatedAt = metaField(FIELD_SUBTYPE_TIMESTAMP, "updatedAt");
+  updatedAt.setAttr("autoSet", "onUpdate");
+  entity.addChild(updatedAt);
+  const primary = meta(new TypeId(TYPE_IDENTITY, IDENTITY_SUBTYPE_PRIMARY), "primary");
+  primary.setAttr("fields", ["id"]);
+  primary.setAttr("generation", "increment");
+  entity.addChild(primary);
+  return entity;
+}
+
+/** Plain entity, NO @autoSet field. */
+function makePlainEntity(): MetaObject {
+  const entity = metaObject(OBJECT_SUBTYPE_ENTITY, "Post");
+  const id = metaField(FIELD_SUBTYPE_LONG, "id");
+  entity.addChild(id);
+  const title = metaField(FIELD_SUBTYPE_STRING, "title");
+  title.setAttr("required", true);
+  entity.addChild(title);
+  const primary = meta(new TypeId(TYPE_IDENTITY, IDENTITY_SUBTYPE_PRIMARY), "primary");
+  primary.setAttr("fields", ["id"]);
+  primary.setAttr("generation", "increment");
+  entity.addChild(primary);
+  return entity;
+}
+
+function makeCtx(obj: MetaObject) {
+  const root = metaRoot();
+  root.addChild(obj);
+  return makeRenderContext({
+    dialect: "sqlite",
+    loadedRoot: root,
+    outDir: "/x",
+    dbImport: "~/server/db",
+    pkMap: buildPkMap(root),
+    relationMap: buildRelationMap(root),
+  });
+}
+
+describe("hasAutoSetFields", () => {
+  test("true when an entity declares an @autoSet field", () => {
+    expect(hasAutoSetFields(makeAutoSetEntity())).toBe(true);
+  });
+  test("false for a plain entity", () => {
+    expect(hasAutoSetFields(makePlainEntity())).toBe(false);
+  });
+});
+
+describe("InsertPreservingSchema (emitted only for @autoSet entities)", () => {
+  test("@autoSet entity emits <Entity>InsertPreservingSchema", () => {
+    const out = renderZodValidators(makeAutoSetEntity()).toString();
+    expect(out).toContain("export const EventInsertPreservingSchema");
+  });
+
+  test("@autoSet columns are VERBATIM in the preserving schema — no now() transform", () => {
+    const out = renderZodValidators(makeAutoSetEntity()).toString();
+    const preserving = out.split("export const EventInsertPreservingSchema")[1] ?? "";
+    // createdAt + updatedAt appear, but NOT with the create-time now() transform.
+    expect(preserving).toContain("createdAt:");
+    expect(preserving).toContain("updatedAt:");
+    expect(preserving).not.toContain("new Date().toISOString()");
+  });
+
+  test("plain entity emits NO preserving schema", () => {
+    const out = renderZodValidators(makePlainEntity()).toString();
+    expect(out).not.toContain("InsertPreservingSchema");
+  });
+});
+
+describe("renderInsertPreservingFn", () => {
+  test("emits insertPreserving<Entity> parsing the preserving schema and inserting verbatim", () => {
+    const entity = makeAutoSetEntity();
+    const out = renderInsertPreservingFn(entity, makeCtx(entity)).toString();
+    expect(out).toContain("insertPreservingEvent");
+    expect(out).toContain("EventInsertPreservingSchema.parse(data)");
+    expect(out).toContain(".insert(");
+    expect(out).toContain(".returning()");
+  });
+});
+
+describe("renderQueriesFile insertPreserving gating", () => {
+  test("@autoSet entity's queries file contains insertPreserving + imports the preserving schema", () => {
+    const entity = makeAutoSetEntity();
+    const out = renderQueriesFile(entity, makeCtx(entity));
+    expect(out).toContain("insertPreservingEvent");
+    expect(out).toContain("EventInsertPreservingSchema");
+  });
+
+  test("plain entity's queries file has NO insertPreserving", () => {
+    const entity = makePlainEntity();
+    const out = renderQueriesFile(entity, makeCtx(entity));
+    expect(out).not.toContain("insertPreserving");
+    expect(out).not.toContain("InsertPreservingSchema");
+  });
+});

server/typescript/packages/codegen-ts/test/templates/auto-set-zod.test.ts

@@ -58,25 +58,29 @@ describe("Zod insert schema honors @autoSet", () => {
   });
 });
 
+/** The field-list body of the emitted UpdateSchema object literal (between its
+ *  `z.object({` and the closing `})`). Bounds the section so assertions can't
+ *  spill into the #203 InsertPreservingSchema that trails the file (which DOES
+ *  carry createdAt verbatim — that's the point). */
+function updateSchemaBody(out: string): string {
+  return out.split("FooUpdateSchema = z.object({")[1]?.split("})")[0] ?? "";
+}
+
 describe("Zod update schema omits onCreate, transforms onUpdate", () => {
   test("@autoSet: onCreate field is OMITTED from update schema", () => {
     const out = renderZodValidators(makeEntity()).toString();
     expect(out).toContain("export const FooUpdateSchema");
-    // createdAt must not appear in UpdateSchema at all
-    // Split on UpdateSchema to check only that section
-    const updateSection = out.split("export const FooUpdateSchema")[1] ?? "";
-    expect(updateSection).not.toContain("createdAt");
+    // createdAt must not appear in the UpdateSchema body at all.
+    expect(updateSchemaBody(out)).not.toContain("createdAt");
   });
 
   test("@autoSet: onUpdate field is present in update schema with transform", () => {
     const out = renderZodValidators(makeEntity()).toString();
-    const updateSection = out.split("export const FooUpdateSchema")[1] ?? "";
-    expect(updateSection).toMatch(/updatedAt:.*optional\(\)\.transform\(\(\) => new Date\(\)\.toISOString\(\)\)/);
+    expect(updateSchemaBody(out)).toMatch(/updatedAt:.*optional\(\)\.transform\(\(\) => new Date\(\)\.toISOString\(\)\)/);
   });
 
   test("ordinary required fields become optional in update schema", () => {
     const out = renderZodValidators(makeEntity()).toString();
-    const updateSection = out.split("export const FooUpdateSchema")[1] ?? "";
-    expect(updateSection).toMatch(/name:.*optional\(\)/);
+    expect(updateSchemaBody(out)).toMatch(/name:.*optional\(\)/);
   });
 });