@palantir/pack.schema 0.5.0 → 0.6.0

package/build/types/defineMigration.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,uBAAuB;AAErC,cAAc,WAAW,WAAyB,UAAU,qBAAqB;AAEjF,cAAc,KAAK,YAAY;;AAI/B,YAAY,iBAAiB;;AAG7B,YAAY,OAAO,UAAU,aAAa;AAE1C,YAAY,cAAc,UAAU,gBACjC,WAAW,KAAI,EAAE,WAAW,eAAe,KAAK,aAAa,KAC1D,EAAE,WAAW,gBAAgB,KAAK,cAAc;AAItD,iBAAiB,cAAc,UAAU,eAAe,OAAO;CAE7D;QAAe;EAAkB,UAAU;GACzC,MAAM,GACN,MAAM,IACL,cAAc,OAAO,KAAK,KAAI;CACjC,SAAS,UAAU;;AAGrB,iBAAiB,aAAa,UAAU,eAAe;CAErD,iBAAiB,kBACf,MAAM,GACN,eAAe,kBACd,aAAa,OAAO,KAAK,KAAI;CAChC,SAAS,SAAS;;AAmEpB,OAAO,iBAAS;OACR,UAAU;OACV,UAAU;EAEhB,QAAQ,GACR,YAAY,QAAQ,cAAc,OAAO,IACxC,IAAI","names":[],"sources":["../../src/defineMigration.ts"],"version":3,"file":"defineMigration.d.ts"}
+{"mappings":"AAgBA,cAAc,uBAAuB;AAErC,cAAc,WAAW,WAAyB,UAAU,qBAAqB;AAEjF,cAAc,KAAK,YAAY;;AAI/B,YAAY,iBAAiB;;AAG7B,YAAY,OAAO,UAAU,aAAa;AAE1C,YAAY,cAAc,UAAU,gBACjC,WAAW,KAAI,EAAE,WAAW,eAAe,KAAK,aAAa,KAC1D,EAAE,WAAW,gBAAgB,KAAK,cAAc;;;;;;;;KAWjD,+CAKD,cACA;gBAAiB;;;;;;;;;;AAUrB,iBAAiB,oBAAoB,aAAa,yBAAyB;UAChE,aAAa,oBAAoB;UACjC,UAAU;;;;;;AAOrB,iBAAiB,qBAAqB;UAC3B,UAAU;;AAGrB,YAAY,eACR,oBAAoB,2BACpB;AAuCJ,iBAAiB,cAAc,UAAU,eAAe,OAAO;CAE7D;QAAe;EAAkB,UAAU;GACzC,MAAM,GACN,MAAM,GACN,UAAU,eACT,cAAc,OAAO,KAAK,KAAI;CACjC,YAAY,gBAAgB,YAC1B,MAAM,IACL,cAAc,KAAK,GAAG;CACzB,SAAS,UAAU;;AAGrB,iBAAiB,aAAa,UAAU,eAAe;CAErD,iBAAiB,kBACf,MAAM,GACN,eAAe,kBACd,aAAa,OAAO,KAAK,KAAI;CAChC,SAAS,SAAS;;;AAwIpB,YAAY,gBAAgB,eAE1B,eAAe,oBAAoB;AAGrC,iBAAiB,gBAAgB,UAAU,WAAW;UAC3C,QAAQ;UACR,WAAW;;;;;;;;;;;;;;AAetB,OAAO,iBAAS;OACR,UAAU;OACV,UAAU;EAEhB,QAAQ,GACR,YAAY,QAAQ,cAAc,OAAO,IACxC,gBAAgB,IAAI;AAqCvB,OAAO,iBAAS;OACR,UAAU;OACV,UAAU;EAEhB,QAAQ,GACR,YAAY,QAAQ,cAAc,OAAO,IACxC,IAAI","names":[],"sources":["../../src/defineMigration.ts"],"version":3,"file":"defineMigration.d.ts"}

package/build/types/defineSchemaUpdate.d.ts

@@ -7,7 +7,6 @@ export interface InitialSchema<T extends ModelDefs = ModelDefs> {
 }
 export interface FieldMigration {
 	readonly derivedFrom: readonly string[];
-	readonly forward: (oldFields: Record<string, unknown>) => unknown;
 }
 export type VersionMigrations = Record<string, Record<string, FieldMigration>>;
 export interface VersionedSchema<T extends ModelDefs = ModelDefs> {

package/build/types/defineSchemaUpdate.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,qBAAqB;AAEnC,cAAc,iBAAiB;AAE/B,iBAAiB,cAAc,UAAU,YAAY,WAAW;UACrD,MAAM;UACN,SAAS;UACT,QAAQ;;AAGnB,iBAAiB,eAAe;UACrB;UACA,UAAU,WAAW;;AAGhC,YAAY,oBAAoB,eAAe,eAAe;AAE9D,iBAAiB,gBAAgB,UAAU,YAAY,WAAW;UACvD,MAAM;UACN,QAAQ;UACR;UACA,UAAU;UACV,aAAa;;AAGxB,YAAY,iBAAiB,UAAU,YAAY,aAC/C,cAAc,KACd,gBAAgB;AAEpB,OAAO,iBAAS,aAAa,UAAU,WAAW,QAAQ,IAAI,cAAc;AAI5E,iBAAiB;CAAa,UAAU;CAAW,UAAU;EAAW;UAC7D;UACA,YAAY,QAAQ,cAAc,OAAO;;AAGpD,OAAO,iBAAS;CAAmB,UAAU;CAAW,UAAU;EAChE,cACA,YAAY,QAAQ,cAAc,OAAO,IACxC,aAAa,GAAG;AAInB,iBAAiB,qBAAqB,UAAU,WAAW;CACzD,gBAAgB,UAAU,WACxB,QAAQ,aAAa,GAAG,KACvB,qBAAqB,IAAI;CAC5B,eAAe,YAAY,oBAAoB,qBAAqB;CACpE,SAAS,gBAAgB;;AA2C3B,OAAO,iBAAS,WAAW,UAAU,WACnC,UAAU,iBAAiB,KAC1B,qBAAqB","names":[],"sources":["../../src/defineSchemaUpdate.ts"],"version":3,"file":"defineSchemaUpdate.d.ts"}
+{"mappings":"AAgBA,cAAc,qBAAqB;AAEnC,cAAc,iBAAiB;AAE/B,iBAAiB,cAAc,UAAU,YAAY,WAAW;UACrD,MAAM;UACN,SAAS;UACT,QAAQ;;AAGnB,iBAAiB,eAAe;UACrB;;AAGX,YAAY,oBAAoB,eAAe,eAAe;AAE9D,iBAAiB,gBAAgB,UAAU,YAAY,WAAW;UACvD,MAAM;UACN,QAAQ;UACR;UACA,UAAU;UACV,aAAa;;AAGxB,YAAY,iBAAiB,UAAU,YAAY,aAC/C,cAAc,KACd,gBAAgB;AAEpB,OAAO,iBAAS,aAAa,UAAU,WAAW,QAAQ,IAAI,cAAc;AAI5E,iBAAiB;CAAa,UAAU;CAAW,UAAU;EAAW;UAC7D;UACA,YAAY,QAAQ,cAAc,OAAO;;AAGpD,OAAO,iBAAS;CAAmB,UAAU;CAAW,UAAU;EAChE,cACA,YAAY,QAAQ,cAAc,OAAO,IACxC,aAAa,GAAG;AAInB,iBAAiB,qBAAqB,UAAU,WAAW;CACzD,gBAAgB,UAAU,WACxB,QAAQ,aAAa,GAAG,KACvB,qBAAqB,IAAI;CAC5B,eAAe,YAAY,oBAAoB,qBAAqB;CACpE,SAAS,gBAAgB;;AAyG3B,OAAO,iBAAS,WAAW,UAAU,WACnC,UAAU,iBAAiB,KAC1B,qBAAqB","names":[],"sources":["../../src/defineSchemaUpdate.ts"],"version":3,"file":"defineSchemaUpdate.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.schema",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "API package for PACK schema functionality",
   "license": "Apache-2.0",
   "repository": {

package/src/__tests__/addFieldOptions.test.ts

@@ -0,0 +1,577 @@
+/*
+ * 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 { describe, expect, it } from "vitest";
+import type { SchemaBuilder } from "../defineMigration.js";
+import { applyMigration, defineMigration } from "../defineMigration.js";
+import { defineRecord } from "../defineRecord.js";
+import { defineSchema, defineSchemaUpdate, nextSchema } from "../defineSchemaUpdate.js";
+import { defineUnion } from "../defineUnion.js";
+import type { RecordDef } from "../defs.js";
+import * as P from "../primitives.js";
+
+describe("addField with upgrade options", () => {
+  const v1 = defineSchema({
+    ShapeBox: defineRecord("ShapeBox", {
+      docs: "A box",
+      fields: {
+        x: P.Double,
+        y: P.Double,
+        color: P.Optional(P.String),
+      },
+    }),
+  });
+
+  it("propagates derivedFrom to versioned upgrades", () => {
+    const colorSplit = defineSchemaUpdate(
+      "colorSplit",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .addField("strokeColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .removeField("color")
+          .build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(colorSplit).build();
+
+    expect(v2.migrations).toBeDefined();
+    expect(v2.migrations?.ShapeBox?.fillColor?.derivedFrom).toEqual(["color"]);
+    expect(v2.migrations?.ShapeBox?.strokeColor?.derivedFrom).toEqual(["color"]);
+    expect(Object.keys(v2.migrations?.ShapeBox?.fillColor ?? {})).toEqual(["derivedFrom"]);
+  });
+
+  it("removeField strips the field from the resulting record fields", () => {
+    const colorSplit = defineSchemaUpdate(
+      "colorSplit",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .removeField("color")
+          .build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(colorSplit).build();
+    const shapeBox = v2.models.ShapeBox;
+    expect(Object.keys(shapeBox.fields).sort()).toEqual([
+      "fillColor",
+      "x",
+      "y",
+    ]);
+  });
+
+  it("explicit withMigrations is merged with addField sugar", () => {
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("fillColor", P.Optional(P.String), {
+          derivedFrom: ["color"],
+        })
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1)
+      .addSchemaUpdate(update)
+      .withMigrations({
+        ShapeBox: {
+          fillColor: {
+            derivedFrom: ["color"],
+          },
+        },
+      })
+      .build();
+
+    expect(v2.migrations?.ShapeBox?.fillColor?.derivedFrom).toEqual(["color"]);
+  });
+
+  it("withMigrations supplements (does not erase) sugar from a different field", () => {
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("fillColor", P.Optional(P.String), {
+          derivedFrom: ["color"],
+        })
+        .addField("opacity", P.Optional(P.Double))
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1)
+      .addSchemaUpdate(update)
+      .withMigrations({
+        ShapeBox: {
+          opacity: {
+            derivedFrom: [],
+          },
+        },
+      })
+      .build();
+
+    expect(v2.migrations?.ShapeBox?.fillColor?.derivedFrom).toEqual(["color"]);
+    expect(v2.migrations?.ShapeBox?.opacity?.derivedFrom).toEqual([]);
+  });
+
+  it("AdditiveFieldOptions { default } is accepted but not added to upgrades", () => {
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("opacity", P.Optional(P.Double), { default: 1.0 })
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1).addSchemaUpdate(update).build();
+    expect(v2.migrations?.ShapeBox?.opacity).toBeUndefined();
+  });
+
+  it("addField without options stays sugar-free", () => {
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("z", P.Double)
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1).addSchemaUpdate(update).build();
+    expect(v2.migrations).toBeUndefined();
+  });
+
+  it("removeField drops any upgrade option staged for that field name", () => {
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("temp", P.Optional(P.String), {
+          derivedFrom: ["color"],
+        })
+        .removeField("temp")
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1).addSchemaUpdate(update).build();
+    expect(v2.migrations).toBeUndefined();
+    expect((v2.models.ShapeBox.fields as Record<string, unknown>).temp).toBeUndefined();
+  });
+
+  it("subsequent addSchemaUpdate does not re-collect options from the prior step", () => {
+    const step1 = defineSchemaUpdate(
+      "step1",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const step2 = defineSchemaUpdate(
+      "step2",
+      (
+        schema: SchemaBuilder<
+          typeof v1.models & { ShapeBox: typeof v1.models.ShapeBox }
+        >,
+      ) => ({
+        ShapeBox: schema.ShapeBox.addField("z", P.Double).build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(step1).addSchemaUpdate(step2).build();
+
+    expect(v2.migrations?.ShapeBox?.fillColor?.derivedFrom).toEqual(["color"]);
+    expect(Object.keys(v2.migrations?.ShapeBox ?? {})).toEqual(["fillColor"]);
+    expect((v2.migrations?.ShapeBox as Record<string, unknown> | undefined)?.z).toBeUndefined();
+  });
+
+  it("does not propagate sugar across nextSchema boundaries", () => {
+    const step1 = defineSchemaUpdate(
+      "step1",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(step1).build();
+    expect(v2.migrations?.ShapeBox?.fillColor).toBeDefined();
+
+    const step2 = defineSchemaUpdate(
+      "step2",
+      (schema: SchemaBuilder<typeof v2.models>) => ({
+        ShapeBox: schema.ShapeBox.addField("z", P.Double).build(),
+      }),
+    );
+    const v3 = nextSchema(v2).addSchemaUpdate(step2).build();
+
+    expect(v3.migrations).toBeUndefined();
+  });
+
+  it("a migration that renames a model keys the upgrade by the output name", () => {
+    const rename = defineSchemaUpdate(
+      "rename",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        // The user reassigns the built def to a different output key.
+        Box: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(rename).build();
+    expect(v2.migrations?.Box?.fillColor?.derivedFrom).toEqual(["color"]);
+    expect(v2.migrations?.ShapeBox).toBeUndefined();
+  });
+
+  it("RecordDef carries no symbol-keyed metadata after a migration", () => {
+    const { models } = applyMigration(v1.models, schema => ({
+      ShapeBox: schema.ShapeBox
+        .addField("fillColor", P.Optional(P.String), {
+          derivedFrom: ["color"],
+        })
+        .build(),
+    }));
+
+    expect(Object.getOwnPropertySymbols(models.ShapeBox)).toEqual([]);
+    const json = JSON.parse(JSON.stringify(models.ShapeBox)) as Record<string, unknown>;
+    expect(Object.keys(json).sort()).toEqual(["docs", "fields", "name", "type"]);
+  });
+
+  it("applyMigration returns undefined upgrades when none are collected", () => {
+    const result = applyMigration(v1.models, schema => ({
+      ShapeBox: schema.ShapeBox.addField("z", P.Double).build(),
+    }));
+    expect(result.upgrades).toBeUndefined();
+  });
+
+  it("applyMigration filters out AdditiveFieldOptions from upgrades", () => {
+    const result = applyMigration(v1.models, schema => ({
+      ShapeBox: schema.ShapeBox
+        .addField("opacity", P.Optional(P.Double), { default: 0.5 })
+        .build(),
+    }));
+    expect(result.upgrades).toBeUndefined();
+  });
+
+  it("defineMigration drops upgrade options silently (lower-level entry point)", () => {
+    // The public defineMigration returns just T & S; it does not surface
+    // upgrades. Callers that need upgrades use applyMigration or addSchemaUpdate.
+    const merged = defineMigration(v1.models, schema => ({
+      ShapeBox: schema.ShapeBox
+        .addField("fillColor", P.Optional(P.String), {
+          derivedFrom: ["color"],
+        })
+        .build(),
+    }));
+
+    expect(merged.ShapeBox.fields.fillColor).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+    expect(Object.getOwnPropertySymbols(merged.ShapeBox)).toEqual([]);
+  });
+
+  // Type of v1.models after a prior step adds an optional-string `temp` field
+  // to ShapeBox. Used to type the input of a later step that calls
+  // `removeField("temp")` — without this, `temp` is not statically known to
+  // be in the field set and the call would fail to type-check.
+  type V1WithTemp = typeof v1.models & {
+    ShapeBox: RecordDef<
+      typeof v1.models.ShapeBox["fields"] & { readonly temp: P.Optional<P.String> }
+    >;
+  };
+
+  it("a later addSchemaUpdate that removes a field also drops its migration", () => {
+    const addTemp = defineSchemaUpdate(
+      "addTemp",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("temp", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const removeTemp = defineSchemaUpdate(
+      "removeTemp",
+      (schema: SchemaBuilder<V1WithTemp>) => ({
+        ShapeBox: schema.ShapeBox.removeField("temp").build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(addTemp).addSchemaUpdate(removeTemp).build();
+
+    expect((v2.models.ShapeBox.fields as Record<string, unknown>).temp).toBeUndefined();
+    expect(v2.migrations).toBeUndefined();
+  });
+
+  it("a later update may remove one upgraded field while adding another", () => {
+    const addTwo = defineSchemaUpdate(
+      "addTwo",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("temp", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const removeTemp = defineSchemaUpdate(
+      "removeTemp",
+      (schema: SchemaBuilder<V1WithTemp>) => ({
+        ShapeBox: schema.ShapeBox.removeField("temp").build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(addTwo).addSchemaUpdate(removeTemp).build();
+
+    expect(Object.keys(v2.migrations?.ShapeBox ?? {})).toEqual(["fillColor"]);
+    expect((v2.migrations?.ShapeBox as Record<string, unknown> | undefined)?.temp).toBeUndefined();
+  });
+
+  it("withMigrations entries are pruned when a later update removes the field", () => {
+    const noop = defineSchemaUpdate(
+      "noop",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("temp", P.Optional(P.String))
+          .build(),
+      }),
+    );
+
+    const removeTemp = defineSchemaUpdate(
+      "removeTemp",
+      (schema: SchemaBuilder<V1WithTemp>) => ({
+        ShapeBox: schema.ShapeBox.removeField("temp").build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1)
+      .addSchemaUpdate(noop)
+      .withMigrations({
+        ShapeBox: {
+          temp: {
+            derivedFrom: ["color"],
+          },
+        },
+      })
+      .addSchemaUpdate(removeTemp)
+      .build();
+
+    expect((v2.models.ShapeBox.fields as Record<string, unknown>).temp).toBeUndefined();
+    expect(v2.migrations).toBeUndefined();
+  });
+
+  it("withMigrations silently drops entries for fields the model no longer has", () => {
+    const v2 = nextSchema(v1)
+      .withMigrations({
+        ShapeBox: {
+          ghost: {
+            derivedFrom: ["color"],
+          },
+        },
+      })
+      .build();
+
+    expect(v2.migrations).toBeUndefined();
+  });
+
+  it("retyping a record into a union drops the prior step's migrations", () => {
+    const Circle = defineRecord("Circle", {
+      docs: "circle",
+      fields: { radius: P.Double },
+    });
+    const Square = defineRecord("Square", {
+      docs: "square",
+      fields: { side: P.Double },
+    });
+
+    const addSugar = defineSchemaUpdate(
+      "addSugar",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String), {
+            derivedFrom: ["color"],
+          })
+          .build(),
+      }),
+    );
+
+    const retype = defineSchemaUpdate(
+      "retype",
+      (
+        _schema: SchemaBuilder<
+          typeof v1.models & { ShapeBox: typeof v1.models.ShapeBox }
+        >,
+      ) => ({
+        Circle,
+        Square,
+        ShapeBox: defineUnion("ShapeBox", {
+          docs: "now a union",
+          variants: { Circle, Square },
+        }),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(addSugar).addSchemaUpdate(retype).build();
+
+    // The merged TS type for the `ShapeBox` key intersects a `RecordDef` with
+    // a `UnionDef`, which collapses to `never` at the type level even though
+    // the runtime override produces the union. Cast for the runtime check.
+    expect((v2.models.ShapeBox as unknown as { type: string }).type).toBe("union");
+    expect(v2.migrations).toBeUndefined();
+  });
+
+  it("UpgradeFieldOptions { derivedFrom, default } captures default in upgrades", () => {
+    // When a derived field also supplies a literal-JSON `default`, the option
+    // object flows into `upgrades` verbatim — the runtime upgrade function
+    // may consult `default` when no source data is present.
+    const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
+      ShapeBox: schema.ShapeBox
+        .addField("fillColor", P.Optional(P.String), {
+          derivedFrom: ["color"],
+          default: "transparent",
+        })
+        .build(),
+    }));
+
+    const v2 = nextSchema(v1).addSchemaUpdate(update).build();
+    expect(v2.migrations?.ShapeBox?.fillColor).toEqual({
+      derivedFrom: ["color"],
+      default: "transparent",
+    });
+  });
+});
+
+// Exercises `assertJsonDefault` via the public `addField()` entry point.
+// `assertJsonDefault` is not exported, so we drive it through the builder.
+// Each rejection case asserts both that the call throws and that the path
+// reported in the error message includes the field name (and, where
+// applicable, a nested key/index) — that path is the user-facing breadcrumb
+// when a default value is malformed.
+describe("addField default value validation (assertJsonDefault)", () => {
+  const v1 = defineSchema({
+    R: defineRecord("R", { docs: "r", fields: { x: P.Double } }),
+  });
+
+  /**
+   * Helper that builds a one-field migration adding `extra` with the given
+   * `default`. Returns the `addField` invocation as a thunk so callers can
+   * either invoke it (success case) or assert it throws (rejection case).
+   */
+  function withDefault(value: unknown): () => unknown {
+    return () =>
+      defineMigration(v1.models, schema => ({
+        R: schema.R
+          .addField("extra", P.Optional(P.String), { default: value as never })
+          .build(),
+      }));
+  }
+
+  describe("accepts literal JSON", () => {
+    it.each([
+      ["string", "hello"],
+      ["number", 42],
+      ["zero", 0],
+      ["negative number", -1.5],
+      ["true", true],
+      ["false", false],
+      ["null", null],
+      ["empty object", {}],
+      ["empty array", []],
+      ["nested plain object", { a: 1, b: { c: "x", d: [1, 2, null] } }],
+      ["nested array of plain objects", [{ x: 1 }, { x: 2 }]],
+    ])("%s", (_label, value) => {
+      expect(withDefault(value)).not.toThrow();
+    });
+  });
+
+  describe("rejects non-JSON values", () => {
+    it("undefined at the top level", () => {
+      // Note: `{ default: undefined }` is structurally the same as `{}` so
+      // it bypasses validation; the real top-level case is `default: NaN`
+      // surfacing as undefined-after-stringify. We test undefined-via-nesting
+      // below where it actually triggers the validator.
+      expect(withDefault(() => undefined)).toThrow(/function is not valid JSON/);
+    });
+
+    it("nested undefined inside an object", () => {
+      expect(withDefault({ a: 1, b: undefined })).toThrow(
+        /addField\("extra"\)\.default\.b: undefined is not valid JSON/,
+      );
+    });
+
+    it("nested undefined inside an array", () => {
+      expect(withDefault([1, undefined, 3])).toThrow(
+        /addField\("extra"\)\.default\[1\]: undefined is not valid JSON/,
+      );
+    });
+
+    it("function", () => {
+      expect(withDefault(() => 1)).toThrow(/function is not valid JSON/);
+    });
+
+    it("symbol", () => {
+      expect(withDefault(Symbol("s"))).toThrow(/symbol is not valid JSON/);
+    });
+
+    it("bigint", () => {
+      expect(withDefault(BigInt(1))).toThrow(/bigint is not valid JSON/);
+    });
+
+    it("Date instance (non-plain object)", () => {
+      expect(withDefault(new Date(0))).toThrow(/Date is not valid JSON/);
+    });
+
+    it("RegExp instance (non-plain object)", () => {
+      expect(withDefault(/foo/)).toThrow(/RegExp is not valid JSON/);
+    });
+
+    it("class instance (non-plain object)", () => {
+      class Widget {
+        readonly id = 1;
+      }
+      expect(withDefault(new Widget())).toThrow(/Widget is not valid JSON/);
+    });
+
+    it("Map (non-plain object)", () => {
+      expect(withDefault(new Map())).toThrow(/Map is not valid JSON/);
+    });
+
+    it("symbol-keyed property on a plain object", () => {
+      const obj: Record<string | symbol, unknown> = { a: 1 };
+      obj[Symbol("k")] = 2;
+      expect(withDefault(obj)).toThrow(
+        /symbol-keyed properties are not valid JSON/,
+      );
+    });
+
+    it("nested non-plain object reports the path", () => {
+      expect(withDefault({ inner: { date: new Date(0) } })).toThrow(
+        /addField\("extra"\)\.default\.inner\.date: Date is not valid JSON/,
+      );
+    });
+  });
+});