@palantir/pack.document-schema.type-gen 0.12.0 → 0.14.0

package/build/esm/utils/schema/__tests__/provenanceScenarios.test.js

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2026 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as P from "@palantir/pack.schema";
+import { defineRecord, defineSchema, defineSchemaUpdate, nextSchema } from "@palantir/pack.schema";
+import { describe, expect, it } from "vitest";
+import { generateInternalFromChain } from "../generateInternalFromSchema.js";
+import { resolveSchemaChain, stripDeprecatedFieldsForSdk } from "../resolveSchemaChain.js";
+function entry(chain, v) {
+  return chain.find(c => c.version === v);
+}
+function recordFields(e, key) {
+  const m = e.ir.models[key];
+  if (m.type !== "record") throw new Error(`${key} not a record`);
+  return Object.fromEntries(m.record.fields.map(f => [f.key, f]));
+}
+function unionMeta(e, key) {
+  const m = e.ir.models[key];
+  if (m.type !== "union") throw new Error(`${key} not a union`);
+  return m.union.metadata;
+}
+describe("provenance — scenarios beyond the demo", () => {
+  const v1 = defineSchema({
+    Box: defineRecord("Box", {
+      docs: "",
+      fields: {
+        a: P.Double
+      }
+    }),
+    OldUnion: P.defineUnion("OldUnion", {
+      docs: "",
+      variants: {
+        box: defineRecord("UVariant", {
+          docs: "",
+          fields: {
+            z: P.Double
+          }
+        })
+      }
+    })
+  });
+  const v2update = defineSchemaUpdate("v2", s => {
+    const Box = s.Box.addField("b", P.Optional(P.String)).build();
+    const Circle = defineRecord("Circle", {
+      docs: "",
+      fields: {
+        r: P.Double
+      }
+    });
+    const NewUnion = P.defineUnion("NewUnion", {
+      docs: "",
+      variants: {
+        c: Circle
+      }
+    });
+    return {
+      Box,
+      Circle,
+      NewUnion
+    };
+  });
+  const v2 = nextSchema(v1).addSchemaUpdate(v2update).build();
+  const v3update = defineSchemaUpdate("v3", s => ({
+    Box: s.Box.addField("c", P.Optional(P.Double)).build()
+  }));
+  const v3 = nextSchema(v2).addSchemaUpdate(v3update).build();
+  it("union defined in v1 stays addedInVersion 1 in every version", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v3);
+    for (const v of [1, 2, 3]) {
+      expect(unionMeta(entry(chain, v), "OldUnion").addedInVersion).toBe(1);
+    }
+  });
+  it("union added in v2 gets addedInVersion 2", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v3);
+    expect(entry(chain, 1).ir.models.NewUnion).toBeUndefined();
+    expect(unionMeta(entry(chain, 2), "NewUnion").addedInVersion).toBe(2);
+    expect(unionMeta(entry(chain, 3), "NewUnion").addedInVersion).toBe(2);
+  });
+  it("record added in v2 gets its fields stamped addedInVersion 2", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v3);
+    expect(entry(chain, 1).ir.models.Circle).toBeUndefined();
+    expect(recordFields(entry(chain, 2), "Circle").r.metadata.addedInVersion).toBe(2);
+    expect(recordFields(entry(chain, 3), "Circle").r.metadata.addedInVersion).toBe(2);
+  });
+  it("field added in v3 to a v1 record gets addedInVersion 3; older fields keep theirs", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v3);
+    const f = recordFields(entry(chain, 3), "Box");
+    expect(f.b.metadata.addedInVersion).toBe(2);
+    expect(f.c.metadata.addedInVersion).toBe(3);
+  });
+  it("hand-built schema provenance is derived from first appearance in the chain", () => {
+    const hand = {
+      type: "versioned",
+      version: 2,
+      previous: {
+        type: "initial",
+        version: 1,
+        models: v1.models
+      },
+      models: {
+        Box: defineRecord("Box", {
+          docs: "",
+          fields: {
+            a: P.Double,
+            b: P.Double
+          }
+        })
+      }
+    };
+    const {
+      chain
+    } = resolveSchemaChain(hand);
+    expect(recordFields(entry(chain, 2), "Box").a.metadata.addedInVersion).toBe(1);
+    expect(recordFields(entry(chain, 2), "Box").b.metadata.addedInVersion).toBe(2);
+    expect(recordFields(entry(chain, 1), "Box").a.metadata.addedInVersion).toBe(1);
+  });
+  it("upgrade lens still records removedFields + derivedFrom for a deprecated field", () => {
+    const b1 = defineSchema({
+      Box: defineRecord("Box", {
+        docs: "",
+        fields: {
+          a: P.Double,
+          color: P.Optional(P.String)
+        }
+      })
+    });
+    const split = defineSchemaUpdate("split", s => ({
+      Box: s.Box.addField("fillColor", P.Optional(P.String), {
+        derivedFrom: ["color"]
+      }).deprecateField("color").build()
+    }));
+    const b2 = nextSchema(b1).addSchemaUpdate(split).build();
+    const resolved = resolveSchemaChain(b2);
+    const stripped = {
+      ...resolved,
+      chain: stripDeprecatedFieldsForSdk(resolved.chain)
+    };
+    const internal = generateInternalFromChain(stripped);
+    expect(internal.upgrades).toContain("removedFields: [\"color\"]");
+    expect(internal.upgrades).toContain("derivedFrom: [\"color\"]");
+  });
+  it("deprecation with and without message both serialize (spread fix #5)", () => {
+    const b1 = defineSchema({
+      Box: defineRecord("Box", {
+        docs: "",
+        fields: {
+          x: P.Optional(P.String),
+          y: P.Optional(P.String)
+        }
+      })
+    });
+    const dep = defineSchemaUpdate("dep", s => ({
+      Box: s.Box.deprecateField("x", "gone").deprecateField("y").build()
+    }));
+    const b2 = nextSchema(b1).addSchemaUpdate(dep).build();
+    const f = recordFields(entry(resolveSchemaChain(b2).chain, 2), "Box");
+    expect(f.x.metadata.deprecatedFromVersion).toBe(2);
+    expect(f.x.metadata.deprecatedMessage).toBe("gone");
+    expect(f.y.metadata.deprecatedFromVersion).toBe(2);
+    expect(f.y.metadata.deprecatedMessage ?? undefined).toBeUndefined();
+  });
+});
+//# sourceMappingURL=provenanceScenarios.test.js.map

package/build/esm/utils/schema/__tests__/provenanceScenarios.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenanceScenarios.test.js","names":["P","defineRecord","defineSchema","defineSchemaUpdate","nextSchema","describe","expect","it","generateInternalFromChain","resolveSchemaChain","stripDeprecatedFieldsForSdk","entry","chain","v","find","c","version","recordFields","e","key","m","ir","models","type","Error","Object","fromEntries","record","fields","map","f","unionMeta","union","metadata","v1","Box","docs","a","Double","OldUnion","defineUnion","variants","box","z","v2update","s","addField","Optional","String","build","Circle","r","NewUnion","v2","addSchemaUpdate","v3update","v3","addedInVersion","toBe","toBeUndefined","b","hand","previous","b1","color","split","derivedFrom","deprecateField","b2","resolved","stripped","internal","upgrades","toContain","x","y","dep","deprecatedFromVersion","deprecatedMessage","undefined"],"sources":["provenanceScenarios.test.ts"],"sourcesContent":["/*\n * Copyright 2026 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport * as P from \"@palantir/pack.schema\";\nimport { defineRecord, defineSchema, defineSchemaUpdate, nextSchema } from \"@palantir/pack.schema\";\nimport { describe, expect, it } from \"vitest\";\nimport type {\n  IFieldDef,\n  IModelDef,\n} from \"../../../lib/pack-docschema-api/pack-docschema-ir/index.js\";\nimport { generateInternalFromChain } from \"../generateInternalFromSchema.js\";\nimport {\n  resolveSchemaChain,\n  stripDeprecatedFieldsForSdk,\n  type VersionedIrEntry,\n} from \"../resolveSchemaChain.js\";\n\nfunction entry(chain: VersionedIrEntry[], v: number): VersionedIrEntry {\n  return chain.find(c => c.version === v)!;\n}\nfunction recordFields(e: VersionedIrEntry, key: string): Record<string, IFieldDef> {\n  const m: IModelDef = e.ir.models[key]!;\n  if (m.type !== \"record\") throw new Error(`${key} not a record`);\n  return Object.fromEntries(m.record.fields.map(f => [f.key, f]));\n}\nfunction unionMeta(e: VersionedIrEntry, key: string) {\n  const m: IModelDef = e.ir.models[key]!;\n  if (m.type !== \"union\") throw new Error(`${key} not a union`);\n  return m.union.metadata;\n}\n\ndescribe(\"provenance — scenarios beyond the demo\", () => {\n  const v1 = defineSchema({\n    Box: defineRecord(\"Box\", { docs: \"\", fields: { a: P.Double } }),\n    OldUnion: P.defineUnion(\"OldUnion\", {\n      docs: \"\",\n      variants: { box: defineRecord(\"UVariant\", { docs: \"\", fields: { z: P.Double } }) },\n    }),\n  });\n\n  const v2update = defineSchemaUpdate(\"v2\", (s: P.SchemaBuilder<typeof v1.models>) => {\n    const Box = s.Box.addField(\"b\", P.Optional(P.String)).build();\n    const Circle = defineRecord(\"Circle\", { docs: \"\", fields: { r: P.Double } });\n    const NewUnion = P.defineUnion(\"NewUnion\", {\n      docs: \"\",\n      variants: { c: Circle },\n    });\n    return { Box, Circle, NewUnion };\n  });\n  const v2 = nextSchema(v1).addSchemaUpdate(v2update).build();\n\n  const v3update = defineSchemaUpdate(\"v3\", (s: P.SchemaBuilder<typeof v2.models>) => ({\n    Box: s.Box.addField(\"c\", P.Optional(P.Double)).build(),\n  }));\n  const v3 = nextSchema(v2).addSchemaUpdate(v3update).build();\n\n  it(\"union defined in v1 stays addedInVersion 1 in every version\", () => {\n    const { chain } = resolveSchemaChain(v3);\n    for (const v of [1, 2, 3]) {\n      expect(unionMeta(entry(chain, v), \"OldUnion\").addedInVersion).toBe(1);\n    }\n  });\n\n  it(\"union added in v2 gets addedInVersion 2\", () => {\n    const { chain } = resolveSchemaChain(v3);\n    expect(entry(chain, 1).ir.models.NewUnion).toBeUndefined();\n    expect(unionMeta(entry(chain, 2), \"NewUnion\").addedInVersion).toBe(2);\n    expect(unionMeta(entry(chain, 3), \"NewUnion\").addedInVersion).toBe(2);\n  });\n\n  it(\"record added in v2 gets its fields stamped addedInVersion 2\", () => {\n    const { chain } = resolveSchemaChain(v3);\n    expect(entry(chain, 1).ir.models.Circle).toBeUndefined();\n    expect(recordFields(entry(chain, 2), \"Circle\").r!.metadata.addedInVersion).toBe(2);\n    expect(recordFields(entry(chain, 3), \"Circle\").r!.metadata.addedInVersion).toBe(2);\n  });\n\n  it(\"field added in v3 to a v1 record gets addedInVersion 3; older fields keep theirs\", () => {\n    const { chain } = resolveSchemaChain(v3);\n    const f = recordFields(entry(chain, 3), \"Box\");\n    expect(f.b!.metadata.addedInVersion).toBe(2);\n    expect(f.c!.metadata.addedInVersion).toBe(3);\n  });\n\n  it(\"hand-built schema provenance is derived from first appearance in the chain\", () => {\n    const hand: P.SchemaDefinition = {\n      type: \"versioned\",\n      version: 2,\n      previous: { type: \"initial\", version: 1, models: v1.models },\n      models: { Box: defineRecord(\"Box\", { docs: \"\", fields: { a: P.Double, b: P.Double } }) },\n    };\n    const { chain } = resolveSchemaChain(hand);\n    expect(recordFields(entry(chain, 2), \"Box\").a!.metadata.addedInVersion).toBe(1);\n    expect(recordFields(entry(chain, 2), \"Box\").b!.metadata.addedInVersion).toBe(2);\n    expect(recordFields(entry(chain, 1), \"Box\").a!.metadata.addedInVersion).toBe(1);\n  });\n\n  it(\"upgrade lens still records removedFields + derivedFrom for a deprecated field\", () => {\n    const b1 = defineSchema({\n      Box: defineRecord(\"Box\", { docs: \"\", fields: { a: P.Double, color: P.Optional(P.String) } }),\n    });\n    const split = defineSchemaUpdate(\"split\", (s: P.SchemaBuilder<typeof b1.models>) => ({\n      Box: s.Box\n        .addField(\"fillColor\", P.Optional(P.String), { derivedFrom: [\"color\"] })\n        .deprecateField(\"color\")\n        .build(),\n    }));\n    const b2 = nextSchema(b1).addSchemaUpdate(split).build();\n\n    const resolved = resolveSchemaChain(b2);\n    const stripped = { ...resolved, chain: stripDeprecatedFieldsForSdk(resolved.chain) };\n    const internal = generateInternalFromChain(stripped);\n    expect(internal.upgrades).toContain(\"removedFields: [\\\"color\\\"]\");\n    expect(internal.upgrades).toContain(\"derivedFrom: [\\\"color\\\"]\");\n  });\n\n  it(\"deprecation with and without message both serialize (spread fix #5)\", () => {\n    const b1 = defineSchema({\n      Box: defineRecord(\"Box\", {\n        docs: \"\",\n        fields: { x: P.Optional(P.String), y: P.Optional(P.String) },\n      }),\n    });\n    const dep = defineSchemaUpdate(\"dep\", (s: P.SchemaBuilder<typeof b1.models>) => ({\n      Box: s.Box.deprecateField(\"x\", \"gone\").deprecateField(\"y\").build(),\n    }));\n    const b2 = nextSchema(b1).addSchemaUpdate(dep).build();\n    const f = recordFields(entry(resolveSchemaChain(b2).chain, 2), \"Box\");\n    expect(f.x!.metadata.deprecatedFromVersion).toBe(2);\n    expect(f.x!.metadata.deprecatedMessage).toBe(\"gone\");\n    expect(f.y!.metadata.deprecatedFromVersion).toBe(2);\n    expect(f.y!.metadata.deprecatedMessage ?? undefined).toBeUndefined();\n  });\n});\n"],"mappings":"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","ignoreList":[]}

package/build/esm/utils/schema/__tests__/resolveSchemaChain.test.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2026 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as P from "@palantir/pack.schema";
+import { defineRecord, defineSchema, defineSchemaUpdate, nextSchema } from "@palantir/pack.schema";
+import { describe, expect, it } from "vitest";
+import { resolveSchemaChain, stripDeprecatedFieldsForSdk } from "../resolveSchemaChain.js";
+
+/** Index a record model's fields by key for a given chain entry. */
+function fieldsByKey(entry, modelKey) {
+  const model = entry.ir.models[modelKey];
+  if (model.type !== "record") throw new Error(`${modelKey} is not a record`);
+  return Object.fromEntries(model.record.fields.map(f => [f.key, f]));
+}
+describe("resolveSchemaChain provenance", () => {
+  const v1 = defineSchema({
+    ShapeBox: defineRecord("ShapeBox", {
+      docs: "A box",
+      fields: {
+        left: P.Double,
+        color: P.Optional(P.String)
+      }
+    })
+  });
+  const colorSplit = defineSchemaUpdate("colorSplit", schema => ({
+    ShapeBox: schema.ShapeBox.addField("fillColor", P.Optional(P.String), {
+      derivedFrom: ["color"]
+    }).addField("strokeColor", P.Optional(P.String), {
+      derivedFrom: ["color"]
+    }).deprecateField("color", "use fillColor/strokeColor").build()
+  }));
+  const v2 = nextSchema(v1).addSchemaUpdate(colorSplit).build();
+  it("derives addedInVersion from first appearance in the chain", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v2);
+    const v2Fields = fieldsByKey(chain.find(c => c.version === 2), "ShapeBox");
+    expect(v2Fields.left.metadata.addedInVersion).toBe(1);
+    expect(v2Fields.fillColor.metadata.addedInVersion).toBe(2);
+    expect(v2Fields.strokeColor.metadata.addedInVersion).toBe(2);
+  });
+  it("caps the chain at maxVersion", () => {
+    const {
+      chain,
+      latestVersion,
+      minVersion
+    } = resolveSchemaChain(v2, 1, {}, 1);
+    expect(chain.map(entry => entry.version)).toEqual([1]);
+    expect(latestVersion).toBe(1);
+    expect(minVersion).toBe(1);
+  });
+  it("rejects a maxVersion that is not in the chain", () => {
+    expect(() => resolveSchemaChain(v2, undefined, {}, 3)).toThrow("maxVersion 3 is not in the schema chain");
+  });
+  it("keeps a deprecated field present and stamps deprecatedFromVersion + message", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v2);
+    const v2Fields = fieldsByKey(chain.find(c => c.version === 2), "ShapeBox");
+    expect(v2Fields.color).toBeDefined();
+    expect(v2Fields.color.metadata.addedInVersion).toBe(1);
+    expect(v2Fields.color.metadata.deprecatedFromVersion).toBe(2);
+    expect(v2Fields.color.metadata.deprecatedMessage).toBe("use fillColor/strokeColor");
+  });
+  it("does not mark the field deprecated in versions before the deprecation", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v2);
+    const v1Fields = fieldsByKey(chain.find(c => c.version === 1), "ShapeBox");
+    expect(v1Fields.color).toBeDefined();
+    expect(v1Fields.color.metadata.deprecatedFromVersion ?? undefined).toBeUndefined();
+    expect(v1Fields.fillColor).toBeUndefined();
+  });
+  it("stripDeprecatedFieldsForSdk drops deprecated fields from v>=deprecation only", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v2);
+    const stripped = stripDeprecatedFieldsForSdk(chain);
+    const v1Fields = fieldsByKey(stripped.find(c => c.version === 1), "ShapeBox");
+    expect(v1Fields.color).toBeDefined();
+    const v2Fields = fieldsByKey(stripped.find(c => c.version === 2), "ShapeBox");
+    expect(v2Fields.color).toBeUndefined();
+    expect(v2Fields.fillColor).toBeDefined();
+    expect(fieldsByKey(chain.find(c => c.version === 2), "ShapeBox").color).toBeDefined();
+  });
+});
+describe("resolveSchemaChain — union provenance", () => {
+  const v1 = defineSchema({
+    Box: defineRecord("Box", {
+      docs: "",
+      fields: {
+        a: P.Double
+      }
+    }),
+    NodeShape: P.defineUnion("NodeShape", {
+      docs: "shape",
+      variants: {
+        box: defineRecord("Inner", {
+          docs: "",
+          fields: {
+            z: P.Double
+          }
+        })
+      }
+    })
+  });
+  const addB = defineSchemaUpdate("addB", schema => ({
+    Box: schema.Box.addField("b", P.Optional(P.String)).build()
+  }));
+  const v2 = nextSchema(v1).addSchemaUpdate(addB).build();
+  it("a v1-defined union stays addedInVersion 1 in every version", () => {
+    const {
+      chain
+    } = resolveSchemaChain(v2);
+    for (const version of [1, 2]) {
+      const union = chain.find(c => c.version === version).ir.models.NodeShape;
+      if (union.type !== "union") throw new Error("NodeShape should be a union");
+      expect(union.union.metadata.addedInVersion).toBe(1);
+    }
+  });
+});
+//# sourceMappingURL=resolveSchemaChain.test.js.map

package/build/esm/utils/schema/__tests__/resolveSchemaChain.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSchemaChain.test.js","names":["P","defineRecord","defineSchema","defineSchemaUpdate","nextSchema","describe","expect","it","resolveSchemaChain","stripDeprecatedFieldsForSdk","fieldsByKey","entry","modelKey","model","ir","models","type","Error","Object","fromEntries","record","fields","map","f","key","v1","ShapeBox","docs","left","Double","color","Optional","String","colorSplit","schema","addField","derivedFrom","deprecateField","build","v2","addSchemaUpdate","chain","v2Fields","find","c","version","metadata","addedInVersion","toBe","fillColor","strokeColor","latestVersion","minVersion","toEqual","undefined","toThrow","toBeDefined","deprecatedFromVersion","deprecatedMessage","v1Fields","toBeUndefined","stripped","Box","a","NodeShape","defineUnion","variants","box","z","addB","union"],"sources":["resolveSchemaChain.test.ts"],"sourcesContent":["/*\n * Copyright 2026 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport * as P from \"@palantir/pack.schema\";\nimport { defineRecord, defineSchema, defineSchemaUpdate, nextSchema } from \"@palantir/pack.schema\";\nimport { describe, expect, it } from \"vitest\";\nimport type {\n  IFieldDef,\n  IModelDef,\n} from \"../../../lib/pack-docschema-api/pack-docschema-ir/index.js\";\nimport {\n  resolveSchemaChain,\n  stripDeprecatedFieldsForSdk,\n  type VersionedIrEntry,\n} from \"../resolveSchemaChain.js\";\n\n/** Index a record model's fields by key for a given chain entry. */\nfunction fieldsByKey(entry: VersionedIrEntry, modelKey: string): Record<string, IFieldDef> {\n  const model: IModelDef = entry.ir.models[modelKey]!;\n  if (model.type !== \"record\") throw new Error(`${modelKey} is not a record`);\n  return Object.fromEntries(model.record.fields.map(f => [f.key, f]));\n}\n\ndescribe(\"resolveSchemaChain provenance\", () => {\n  const v1 = defineSchema({\n    ShapeBox: defineRecord(\"ShapeBox\", {\n      docs: \"A box\",\n      fields: { left: P.Double, color: P.Optional(P.String) },\n    }),\n  });\n\n  const colorSplit = defineSchemaUpdate(\n    \"colorSplit\",\n    (schema: P.SchemaBuilder<typeof v1.models>) => ({\n      ShapeBox: schema.ShapeBox\n        .addField(\"fillColor\", P.Optional(P.String), { derivedFrom: [\"color\"] })\n        .addField(\"strokeColor\", P.Optional(P.String), { derivedFrom: [\"color\"] })\n        .deprecateField(\"color\", \"use fillColor/strokeColor\")\n        .build(),\n    }),\n  );\n\n  const v2 = nextSchema(v1).addSchemaUpdate(colorSplit).build();\n\n  it(\"derives addedInVersion from first appearance in the chain\", () => {\n    const { chain } = resolveSchemaChain(v2);\n    const v2Fields = fieldsByKey(chain.find(c => c.version === 2)!, \"ShapeBox\");\n\n    expect(v2Fields.left!.metadata.addedInVersion).toBe(1);\n    expect(v2Fields.fillColor!.metadata.addedInVersion).toBe(2);\n    expect(v2Fields.strokeColor!.metadata.addedInVersion).toBe(2);\n  });\n\n  it(\"caps the chain at maxVersion\", () => {\n    const { chain, latestVersion, minVersion } = resolveSchemaChain(v2, 1, {}, 1);\n\n    expect(chain.map(entry => entry.version)).toEqual([1]);\n    expect(latestVersion).toBe(1);\n    expect(minVersion).toBe(1);\n  });\n\n  it(\"rejects a maxVersion that is not in the chain\", () => {\n    expect(() => resolveSchemaChain(v2, undefined, {}, 3)).toThrow(\n      \"maxVersion 3 is not in the schema chain\",\n    );\n  });\n\n  it(\"keeps a deprecated field present and stamps deprecatedFromVersion + message\", () => {\n    const { chain } = resolveSchemaChain(v2);\n    const v2Fields = fieldsByKey(chain.find(c => c.version === 2)!, \"ShapeBox\");\n\n    expect(v2Fields.color).toBeDefined();\n    expect(v2Fields.color!.metadata.addedInVersion).toBe(1);\n    expect(v2Fields.color!.metadata.deprecatedFromVersion).toBe(2);\n    expect(v2Fields.color!.metadata.deprecatedMessage).toBe(\"use fillColor/strokeColor\");\n  });\n\n  it(\"does not mark the field deprecated in versions before the deprecation\", () => {\n    const { chain } = resolveSchemaChain(v2);\n    const v1Fields = fieldsByKey(chain.find(c => c.version === 1)!, \"ShapeBox\");\n\n    expect(v1Fields.color).toBeDefined();\n    expect(v1Fields.color!.metadata.deprecatedFromVersion ?? undefined).toBeUndefined();\n    expect(v1Fields.fillColor).toBeUndefined();\n  });\n\n  it(\"stripDeprecatedFieldsForSdk drops deprecated fields from v>=deprecation only\", () => {\n    const { chain } = resolveSchemaChain(v2);\n    const stripped = stripDeprecatedFieldsForSdk(chain);\n\n    const v1Fields = fieldsByKey(stripped.find(c => c.version === 1)!, \"ShapeBox\");\n    expect(v1Fields.color).toBeDefined();\n\n    const v2Fields = fieldsByKey(stripped.find(c => c.version === 2)!, \"ShapeBox\");\n    expect(v2Fields.color).toBeUndefined();\n    expect(v2Fields.fillColor).toBeDefined();\n\n    expect(fieldsByKey(chain.find(c => c.version === 2)!, \"ShapeBox\").color).toBeDefined();\n  });\n});\n\ndescribe(\"resolveSchemaChain — union provenance\", () => {\n  const v1 = defineSchema({\n    Box: defineRecord(\"Box\", { docs: \"\", fields: { a: P.Double } }),\n    NodeShape: P.defineUnion(\"NodeShape\", {\n      docs: \"shape\",\n      variants: { box: defineRecord(\"Inner\", { docs: \"\", fields: { z: P.Double } }) },\n    }),\n  });\n  const addB = defineSchemaUpdate(\n    \"addB\",\n    (schema: P.SchemaBuilder<typeof v1.models>) => ({\n      Box: schema.Box.addField(\"b\", P.Optional(P.String)).build(),\n    }),\n  );\n  const v2 = nextSchema(v1).addSchemaUpdate(addB).build();\n\n  it(\"a v1-defined union stays addedInVersion 1 in every version\", () => {\n    const { chain } = resolveSchemaChain(v2);\n    for (const version of [1, 2]) {\n      const union = chain.find(c => c.version === version)!.ir.models.NodeShape!;\n      if (union.type !== \"union\") throw new Error(\"NodeShape should be a union\");\n      expect(union.union.metadata.addedInVersion).toBe(1);\n    }\n  });\n});\n"],"mappings":"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","ignoreList":[]}

package/build/esm/utils/schema/generateInternalFromSchema.js

@@ -16,12 +16,18 @@
 
 import { GENERATED_FILE_HEADER } from "../generatedFileHeader.js";
 import { convertFieldTypeToDescriptor, convertFieldTypeToInternalTypeScript, convertFieldTypeToInternalZod } from "../ir/irFieldHelpers.js";
-import { chainHasDerivedFields } from "./resolveSchemaChain.js";
+import { chainNeedsUpgradeFns } from "./resolveSchemaChain.js";
 
 /** Collected info about all fields for a model across all versions. */
 
 /**
  * Represents an upgrade step for a model between version transitions.
+ *
+ * `fields` only contains entries that require lens treatment — derived fields
+ * (`derivedFrom.length > 0`) and required additive fields (`derivedFrom.length
+ * === 0 && !isOptional`). Optional additive fields are absent because
+ * `undefined` is a legal value at the current version and the lens has no
+ * work to do.
  */
 
 /**
@@ -30,6 +36,9 @@ import { chainHasDerivedFields } from "./resolveSchemaChain.js";
 function sortedEntries(map) {
   return Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
 }
+function getAddedInVersion(fieldInfo) {
+  return Math.min(...fieldInfo.presentInVersions);
+}
 
 /**
  * Collect all record model info across all versions and compute upgrade steps.
@@ -87,25 +96,25 @@ function collectRecordModels(chain) {
       const prevFields = new Set(prevModelDef.record.fields.map(f => f.key));
       const currFields = new Set(currModelDef.record.fields.map(f => f.key));
 
-      // Fields added in this version
+      // Fields added in this version that require lens treatment. Optional
+      // additive fields are skipped — `undefined` is a legal v_current value
+      // for them, so the lens has nothing to invent.
       const addedFields = new Map();
       const recordUpgrades = currEntry.migrations?.[modelKey];
-      for (const fieldKey of currFields) {
-        if (!prevFields.has(fieldKey)) {
-          const annotation = recordUpgrades?.[fieldKey];
-          if (annotation != null) {
-            addedFields.set(fieldKey, {
-              derivedFrom: [...annotation.derivedFrom]
-            });
-          } else {
-            addedFields.set(fieldKey, {
-              derivedFrom: []
-            });
-          }
-        }
+      for (const field of currModelDef.record.fields) {
+        const fieldKey = field.key;
+        if (prevFields.has(fieldKey)) continue;
+        const isOptional = field.isOptional === true;
+        const annotation = recordUpgrades?.[fieldKey];
+        const derivedFrom = annotation != null ? [...annotation.derivedFrom] : [];
+        if (derivedFrom.length === 0 && isOptional) continue;
+        addedFields.set(fieldKey, {
+          derivedFrom,
+          isOptional
+        });
       }
 
-      // Fields removed in this version
+      // Fields absent from this version relative to the previous one (i.e. deprecated fields).
       const removedFields = [];
       for (const fieldKey of prevFields) {
         if (!currFields.has(fieldKey)) {
@@ -224,7 +233,7 @@ function generateUpgrades(allRecordModels, latestIr) {
     output += `  allFields: {\n`;
     for (const [fieldName, fieldInfo] of sortedEntries(model.allFields)) {
       const typeDescriptor = convertFieldTypeToDescriptor(fieldInfo.fieldType, fieldInfo.isOptional);
-      output += `    ${fieldName}: { type: ${typeDescriptor} },\n`;
+      output += `    ${fieldName}: { type: ${typeDescriptor}, addedInVersion: ${getAddedInVersion(fieldInfo)} },\n`;
     }
     output += `  },\n`;
 
@@ -237,9 +246,6 @@ function generateUpgrades(allRecordModels, latestIr) {
       for (const [fieldName, fieldMeta] of step.fields) {
         output += `        ${fieldName}: {\n`;
         output += `          derivedFrom: [${fieldMeta.derivedFrom.map(d => `"${d}"`).join(", ")}],\n`;
-        if (fieldMeta.default !== undefined) {
-          output += `          default: ${JSON.stringify(fieldMeta.default)},\n`;
-        }
         output += `        },\n`;
       }
       output += `      },\n`;
@@ -292,16 +298,21 @@ function generateInternalSchemaContent(allRecordModels) {
  * Generate _internal/upgradeFns.ts content: a typed `DocumentUpgradeFns`
  * interface enumerating every upgrade function the app must supply at boot.
  *
- * For every `(modelName, v${version}, fieldName)` triple where `derivedFrom` is
- * non-empty, emit a property typed
- * `(oldFields: Pick<<Model>__v<prior>, derivedFrom[number]>) => <Model>__v<current>[fieldName]`.
- * Additive fields (empty `derivedFrom`) are intentionally absent — they are
- * handled by the structural `default` in `_internal/upgrades.ts`.
+ * For each `(modelName, v${version}, fieldName)` triple in a step's `fields`,
+ * emit one property:
+ *  - Derived (`derivedFrom.length > 0`):
+ *    `(oldFields: Pick<<Model>__v<prior>, derivedFrom[number]>) => <Model>__v<current>[fieldName]`.
+ *  - Required additive (`derivedFrom.length === 0`):
+ *    `() => <Model>__v<current>[fieldName]`.
+ *
+ * Optional additive fields are filtered out at step-collection time and don't
+ * appear here — `undefined` is a legal v<current> value for them, so the app
+ * has no obligation to invent one.
  *
  * The interface is consumed by the generated `DocumentModel` factory in
- * `models.ts`, which requires it as a parameter when the schema has any
- * derived fields. Schemas without derived fields emit an empty interface
- * (still exported for type-uniformity in downstream code).
+ * `models.ts`, which requires it as a parameter when the schema needs any
+ * upgrade functions. Schemas with no required fields added past v1 emit an
+ * empty interface (still exported for type-uniformity in downstream code).
  */
 function generateUpgradeFns(chain, allRecordModels) {
   const perModel = new Map();
@@ -313,7 +324,6 @@ function generateUpgradeFns(chain, allRecordModels) {
       const priorVersion = chain[currentIdx - 1].version;
       const fields = [];
       for (const [fieldName, fieldMeta] of step.fields) {
-        if (fieldMeta.derivedFrom.length === 0) continue;
         fields.push({
           fieldName,
           derivedFrom: [...fieldMeta.derivedFrom]
@@ -330,7 +340,10 @@ function generateUpgradeFns(chain, allRecordModels) {
         priorVersion,
         fields
       });
-      neededTypes.add(`${modelKey}__v${priorVersion}`);
+      // Prior-version type only needed when at least one field derives from it.
+      if (fields.some(f => f.derivedFrom.length > 0)) {
+        neededTypes.add(`${modelKey}__v${priorVersion}`);
+      }
       neededTypes.add(`${modelKey}__v${step.addedInVersion}`);
     }
   }
@@ -343,7 +356,10 @@ function generateUpgradeFns(chain, allRecordModels) {
   output += `/**\n`;
   output += ` * Typed upgrade functions the application must supply at boot. Coverage is\n`;
   output += ` * exhaustive: missing or extra entries fail type-check at the \`DocumentModel(...)\`\n`;
-  output += ` * call site. Additive fields (empty \`derivedFrom\`) are intentionally absent.\n`;
+  output += ` * call site. Derived fields receive their declared source fields; required\n`;
+  output += ` * additive fields receive no arguments. Optional additive fields are absent\n`;
+  output += ` * — \`undefined\` is a legal value at the new version, so the runtime lens\n`;
+  output += ` * leaves them alone.\n`;
   output += ` */\n`;
   if (perModel.size === 0) {
     output += `// eslint-disable-next-line @typescript-eslint/no-empty-object-type\n`;
@@ -355,8 +371,13 @@ function generateUpgradeFns(chain, allRecordModels) {
       for (const step of steps) {
         output += `    v${step.currentVersion}: {\n`;
         for (const f of step.fields) {
-          const pickKeys = f.derivedFrom.map(d => `"${d}"`).join(" | ");
-          output += `      ${f.fieldName}: (oldFields: Pick<${modelKey}__v${step.priorVersion}, ${pickKeys}>) => ${modelKey}__v${step.currentVersion}["${f.fieldName}"];\n`;
+          const returnType = `${modelKey}__v${step.currentVersion}["${f.fieldName}"]`;
+          if (f.derivedFrom.length === 0) {
+            output += `      ${f.fieldName}: () => ${returnType};\n`;
+          } else {
+            const pickKeys = f.derivedFrom.map(d => `"${d}"`).join(" | ");
+            output += `      ${f.fieldName}: (oldFields: Pick<${modelKey}__v${step.priorVersion}, ${pickKeys}>) => ${returnType};\n`;
+          }
         }
         output += `    };\n`;
       }
@@ -377,7 +398,7 @@ export function generateInternalFromChain(resolved) {
   } = resolved;
   const latestIr = chain[chain.length - 1].ir;
   const allRecordModels = collectRecordModels(chain);
-  const internalTypes = generateInternalTypes(allRecordModels) + (chainHasDerivedFields(chain) ? generatePerVersionInternalTypes(chain) : "");
+  const internalTypes = generateInternalTypes(allRecordModels) + (chainNeedsUpgradeFns(chain) ? generatePerVersionInternalTypes(chain) : "");
   const upgrades = generateUpgrades(allRecordModels, latestIr);
   const internalSchema = generateInternalSchemaContent(allRecordModels);
   const internalUpgradeFns = generateUpgradeFns(chain, allRecordModels);