@palantir/pack.schema 0.7.0 → 0.9.0

package/src/__tests__/addFieldOptions.test.ts

@@ -20,7 +20,6 @@ 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", () => {
@@ -46,7 +45,7 @@ describe("addField with upgrade options", () => {
           .addField("strokeColor", P.Optional(P.String), {
             derivedFrom: ["color"],
           })
-          .removeField("color")
+          .deprecateField("color")
           .build(),
       }),
     );
@@ -59,7 +58,7 @@ describe("addField with upgrade options", () => {
     expect(Object.keys(v2.migrations?.ShapeBox?.fillColor ?? {})).toEqual(["derivedFrom"]);
   });
 
-  it("removeField strips the field from the resulting record fields", () => {
+  it("deprecateField keeps the field and records the deprecation", () => {
     const colorSplit = defineSchemaUpdate(
       "colorSplit",
       (schema: SchemaBuilder<typeof v1.models>) => ({
@@ -67,7 +66,7 @@ describe("addField with upgrade options", () => {
           .addField("fillColor", P.Optional(P.String), {
             derivedFrom: ["color"],
           })
-          .removeField("color")
+          .deprecateField("color", "use fillColor/strokeColor")
           .build(),
       }),
     );
@@ -75,10 +74,29 @@ describe("addField with upgrade options", () => {
     const v2 = nextSchema(v1).addSchemaUpdate(colorSplit).build();
     const shapeBox = v2.models.ShapeBox;
     expect(Object.keys(shapeBox.fields).sort()).toEqual([
+      "color",
       "fillColor",
       "x",
       "y",
     ]);
+    expect(v2.deprecations?.ShapeBox?.color).toEqual({
+      fromVersion: 2,
+      message: "use fillColor/strokeColor",
+    });
+  });
+
+  it("deprecateField without a message records the version only", () => {
+    const update = defineSchemaUpdate(
+      "deprecateColor",
+      (schema: SchemaBuilder<typeof v1.models>) => ({
+        ShapeBox: schema.ShapeBox.deprecateField("color").build(),
+      }),
+    );
+
+    const v2 = nextSchema(v1).addSchemaUpdate(update).build();
+    expect(v2.deprecations?.ShapeBox?.color).toEqual({ fromVersion: 2 });
+    // Field remains present.
+    expect((v2.models.ShapeBox.fields as Record<string, unknown>).color).toBeDefined();
   });
 
   it("explicit withMigrations is merged with addField sugar", () => {
@@ -129,17 +147,6 @@ describe("addField with upgrade options", () => {
     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
@@ -151,19 +158,19 @@ describe("addField with upgrade options", () => {
     expect(v2.migrations).toBeUndefined();
   });
 
-  it("removeField drops any upgrade option staged for that field name", () => {
+  it("deprecateField on an existing field does not affect a new field's upgrade option", () => {
     const update = defineSchemaUpdate("update", (schema: SchemaBuilder<typeof v1.models>) => ({
       ShapeBox: schema.ShapeBox
-        .addField("temp", P.Optional(P.String), {
+        .addField("fillColor", P.Optional(P.String), {
           derivedFrom: ["color"],
         })
-        .removeField("temp")
+        .deprecateField("color")
         .build(),
     }));
 
     const v2 = nextSchema(v1).addSchemaUpdate(update).build();
-    expect(v2.migrations).toBeUndefined();
-    expect((v2.models.ShapeBox.fields as Record<string, unknown>).temp).toBeUndefined();
+    expect(v2.migrations?.ShapeBox?.fillColor?.derivedFrom).toEqual(["color"]);
+    expect(v2.deprecations?.ShapeBox?.color).toBeDefined();
   });
 
   it("subsequent addSchemaUpdate does not re-collect options from the prior step", () => {
@@ -261,15 +268,6 @@ describe("addField with upgrade options", () => {
     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.
@@ -288,102 +286,6 @@ describe("addField with upgrade options", () => {
     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({
@@ -443,135 +345,4 @@ describe("addField with upgrade options", () => {
     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/,
-      );
-    });
-  });
 });

package/src/defineMigration.ts

@@ -34,81 +34,19 @@ export type SchemaBuilder<T extends ModelDefs> = {
 };
 
 /**
- * Recursive literal-JSON type. Constrains schema-time `default` values to
- * data that JSON-serializes losslessly — no `Date`, `RegExp`, functions, class
- * instances, or `undefined`. Mirrors the `JsonValue` exported by
- * `@palantir/pack.document-schema.model-types`; kept local here to avoid a
- * package dependency from `pack.schema`.
- */
-type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-/**
- * Upgrade options for a field whose value is derived from prior-version fields.
- * Supplied as the third argument to `addField`; surfaced by `applyMigration`
- * as part of `MigrationResult.upgrades`. Declares the structural dependency
- * (`derivedFrom`) and an optional literal JSON `default` used when no source
- * data exists. The runtime forward function is supplied separately via the
- * generated `DocumentModel(...)` factory's `UpgradeFns` parameter.
+ * Upgrade options for a field added in this version. Supplied as the third
+ * argument to `addField`; surfaced by `applyMigration` as part of
+ * `MigrationResult.upgrades`. Declares the structural dependency
+ * (`derivedFrom`) the runtime lens uses to decide when to invoke the
+ * upgrade function. The function itself — derived or constant — is supplied
+ * at boot via the generated `DocumentModel(...)` factory's `UpgradeFns`
+ * parameter.
  */
 export interface UpgradeFieldOptions<TOld extends Record<string, unknown>> {
   readonly derivedFrom: ReadonlyArray<keyof TOld & string>;
-  readonly default?: JsonValue;
 }
 
-/**
- * Options for a purely additive field. `default` is literal JSON only;
- * validated at `addField()` call time.
- */
-export interface AdditiveFieldOptions {
-  readonly default?: JsonValue;
-}
-
-export type FieldOptions =
-  | UpgradeFieldOptions<Record<string, unknown>>
-  | AdditiveFieldOptions;
-
-/**
- * Recursively assert `value` is representable as literal JSON. Rejects `Date`,
- * `RegExp`, functions, class instances, symbol-keyed properties, `undefined`
- * (anywhere — top-level or nested), `symbol`, and `bigint`. Throws on the
- * first offending value, naming the path for debuggability.
- */
-function assertJsonDefault(value: unknown, path: string): void {
-  // eslint-disable-next-line eqeqeq -- need to distinguish null (valid JSON) from undefined (not).
-  if (value === null) return;
-  const t = typeof value;
-  if (t === "undefined") {
-    throw new Error(`Invalid JSON default at ${path}: undefined is not valid JSON`);
-  }
-  if (t === "string" || t === "number" || t === "boolean") return;
-  if (t === "function" || t === "symbol" || t === "bigint") {
-    throw new Error(`Invalid JSON default at ${path}: ${t} is not valid JSON`);
-  }
-  if (Array.isArray(value)) {
-    for (let i = 0; i < value.length; i++) {
-      assertJsonDefault(value[i], `${path}[${i}]`);
-    }
-    return;
-  }
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== Object.prototype && proto != null) {
-    const ctorName = (value as { constructor?: { name?: string } }).constructor?.name
-      ?? "non-plain object";
-    throw new Error(`Invalid JSON default at ${path}: ${ctorName} is not valid JSON`);
-  }
-  if (Object.getOwnPropertySymbols(value as object).length > 0) {
-    throw new Error(`Invalid JSON default at ${path}: symbol-keyed properties are not valid JSON`);
-  }
-  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    assertJsonDefault(v, `${path}.${k}`);
-  }
-}
+export type FieldOptions = UpgradeFieldOptions<Record<string, unknown>>;
 
 export interface RecordBuilder<T extends Record<string, Type>> {
   // TODO: builders should support arg types and resolveModels to refs
@@ -117,9 +55,10 @@ export interface RecordBuilder<T extends Record<string, Type>> {
     type: V,
     options?: FieldOptions,
   ): RecordBuilder<T & { [k in K]: V }>;
-  removeField<K extends keyof T & string>(
+  deprecateField<K extends keyof T & string>(
     name: K,
-  ): RecordBuilder<Omit<T, K>>;
+    message?: string,
+  ): RecordBuilder<T>;
   build(): RecordDef<T>;
 }
 
@@ -174,14 +113,29 @@ class UnionBuilderImpl<S extends UnionVariants> implements UnionBuilder<S> {
  */
 const UPGRADE_OPTIONS_CARRIER = "__pack_upgrade_options__";
 
+/**
+ * Non-enumerable carrier property attached to a `RecordDef` by
+ * `RecordBuilderImpl.build()` when the builder has collected one or more
+ * `deprecateField` calls. `applyMigration` reads this and then deletes the
+ * property, so the returned `RecordDef` is structurally clean. Maps field name
+ * → its deprecation info.
+ */
+const DEPRECATED_FIELDS_CARRIER = "__pack_deprecated_fields__";
+
+export interface FieldDeprecation {
+  readonly message?: string;
+}
+
 class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
   private readonly name: string;
   private readonly fields: T;
   private readonly upgradeOptions: ReadonlyMap<string, FieldOptions>;
+  private readonly deprecatedFields: ReadonlyMap<string, FieldDeprecation>;
 
   constructor(
     initialRecordDef: RecordDef<T>,
     upgradeOptions?: ReadonlyMap<string, FieldOptions>,
+    deprecatedFields?: ReadonlyMap<string, FieldDeprecation>,
   ) {
     this.name = initialRecordDef.name;
     this.fields = { ...initialRecordDef.fields };
@@ -189,6 +143,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
     // they are NOT inherited from the prior version's RecordDef, because each
     // version's upgrades describe a specific version transition.
     this.upgradeOptions = new Map<string, FieldOptions>(upgradeOptions ?? []);
+    this.deprecatedFields = new Map<string, FieldDeprecation>(deprecatedFields ?? []);
   }
 
   // TODO: resolve field value from arg instead
@@ -197,9 +152,6 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
     value: V,
     options?: FieldOptions,
   ): RecordBuilder<T & Record<K, V>> {
-    if (options != null && "default" in options && options.default !== undefined) {
-      assertJsonDefault(options.default, `addField("${name}").default`);
-    }
     const next = new Map(this.upgradeOptions);
     if (options != null) {
       next.set(name, options);
@@ -212,24 +164,26 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         docs: "",
       },
       next,
+      this.deprecatedFields,
     );
   }
 
-  removeField<K extends keyof T & string>(
+  deprecateField<K extends keyof T & string>(
     name: K,
-  ): RecordBuilder<Omit<T, K>> {
-    const { [name]: _removed, ...rest } = this.fields;
-    const next = new Map(this.upgradeOptions);
-    next.delete(name);
+    message?: string,
+  ): RecordBuilder<T> {
+    const next = new Map(this.deprecatedFields);
+    next.set(name, { message });
     return new RecordBuilderImpl(
       {
         type: ModelDefType.RECORD,
         name: this.name,
-        fields: rest as RecordFields,
+        fields: { ...this.fields },
         docs: "",
       },
+      this.upgradeOptions,
       next,
-    ) as unknown as RecordBuilder<Omit<T, K>>;
+    );
   }
 
   build(): RecordDef<T> {
@@ -247,6 +201,14 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         writable: false,
       });
     }
+    if (this.deprecatedFields.size > 0) {
+      Object.defineProperty(result, DEPRECATED_FIELDS_CARRIER, {
+        value: this.deprecatedFields,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+      });
+    }
     return result;
   }
 }
@@ -270,22 +232,29 @@ export type FieldUpgrades = Record<
   Record<string, UpgradeFieldOptions<Record<string, unknown>>>
 >;
 
+export type FieldDeprecations = Record<
+  string,
+  Record<string, FieldDeprecation>
+>;
+
 export interface MigrationResult<M extends ModelDefs> {
   readonly models: M;
   readonly upgrades?: FieldUpgrades;
+  readonly deprecations?: FieldDeprecations;
 }
 
 /**
- * Lower-level entry point that returns both the merged models AND any
- * `UpgradeFieldOptions` collected via `addField(name, type, options)` during
- * the migration callback. Used by `addSchemaUpdate` to fold sugar-form
- * upgrades into a `VersionedSchema`'s migrations map.
+ * Lower-level entry point that returns the merged models plus the per-field
+ * metadata collected during the migration callback: `UpgradeFieldOptions` from
+ * `addField(name, type, options)` and deprecations from `deprecateField(name)`.
+ * Used by `addSchemaUpdate` to fold sugar-form upgrades into a
+ * `VersionedSchema`'s migrations map and deprecations into its deprecations map.
  *
- * Each `RecordBuilderImpl.build()` attaches its collected options to the
- * produced `RecordDef` via a non-enumerable carrier property; this function
- * walks the merged result, extracts the options keyed by the user's chosen
- * output key (so renames are handled), and strips the carrier so the returned
- * `RecordDef`s are structurally clean.
+ * Each `RecordBuilderImpl.build()` attaches its collected upgrade options and
+ * deprecations to the produced `RecordDef` via two non-enumerable carrier
+ * properties; this function walks the merged result, extracts both keyed by the
+ * user's chosen output key (so renames are handled), and strips the carriers so
+ * the returned `RecordDef`s are structurally clean.
  */
 export function applyMigration<
   const T extends ModelDefs,
@@ -298,35 +267,48 @@ export function applyMigration<
   const merged = { ...models, ...migration(builders) } as T & S;
 
   const upgrades: FieldUpgrades = {};
+  const deprecations: FieldDeprecations = {};
   for (const [modelKey, def] of Object.entries(merged)) {
     if (!isRecordDef(def)) continue;
     const carrier = def as unknown as Record<string, unknown>;
     const opts = carrier[UPGRADE_OPTIONS_CARRIER] as
       | ReadonlyMap<string, FieldOptions>
       | undefined;
-    if (opts == null) continue;
-    // Strip the carrier so the returned RecordDef is structurally clean.
-    delete carrier[UPGRADE_OPTIONS_CARRIER];
-    const fieldEntries: Record<
-      string,
-      UpgradeFieldOptions<Record<string, unknown>>
-    > = {};
-    for (const [fieldName, options] of opts) {
-      // Only `UpgradeFieldOptions` (which declare `derivedFrom`) flow into the
-      // upgrades map; `AdditiveFieldOptions` carry only a literal `default`
-      // and have no read-time lens effect.
-      if ("derivedFrom" in options) {
+    if (opts != null) {
+      // Strip the carrier so the returned RecordDef is structurally clean.
+      delete carrier[UPGRADE_OPTIONS_CARRIER];
+      const fieldEntries: Record<
+        string,
+        UpgradeFieldOptions<Record<string, unknown>>
+      > = {};
+      for (const [fieldName, options] of opts) {
         fieldEntries[fieldName] = options;
       }
+      if (Object.keys(fieldEntries).length > 0) {
+        upgrades[modelKey] = fieldEntries;
+      }
     }
-    if (Object.keys(fieldEntries).length > 0) {
-      upgrades[modelKey] = fieldEntries;
+
+    const deprecated = carrier[DEPRECATED_FIELDS_CARRIER] as
+      | ReadonlyMap<string, FieldDeprecation>
+      | undefined;
+    if (deprecated != null) {
+      // Strip the carrier so the returned RecordDef is structurally clean.
+      delete carrier[DEPRECATED_FIELDS_CARRIER];
+      const fieldEntries: Record<string, FieldDeprecation> = {};
+      for (const [fieldName, info] of deprecated) {
+        fieldEntries[fieldName] = info;
+      }
+      if (Object.keys(fieldEntries).length > 0) {
+        deprecations[modelKey] = fieldEntries;
+      }
     }
   }
 
   return {
     models: merged,
     upgrades: Object.keys(upgrades).length > 0 ? upgrades : undefined,
+    deprecations: Object.keys(deprecations).length > 0 ? deprecations : undefined,
   };
 }