@palantir/pack.document-schema.model-types 0.7.0 → 0.8.0

package/.turbo/turbo-lint.log

@@ -1,4 +1,4 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 lint /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 lint /home/runner/work/pack/pack/packages/document-schema/model-types
 > eslint ./src && dprint check --config $(find-up dprint.json) --allow-no-files
 

package/.turbo/turbo-transpileBrowser.log

@@ -1,5 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 transpileBrowser /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 transpileBrowser /home/runner/work/pack/pack/packages/document-schema/model-types
 > monorepo-transpile -f esm -m bundle -t browser
 
 [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`

package/.turbo/turbo-transpileCjs.log

@@ -1,5 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 transpileCjs /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 transpileCjs /home/runner/work/pack/pack/packages/document-schema/model-types
 > monorepo-transpile -f cjs -m bundle -t node
 
 [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`

package/.turbo/turbo-transpileEsm.log

@@ -1,5 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 transpileEsm /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 transpileEsm /home/runner/work/pack/pack/packages/document-schema/model-types
 > monorepo-transpile -f esm -m bundle -t node
 
 [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`

package/.turbo/turbo-transpileTypes.log

@@ -1,5 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 transpileTypes /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 transpileTypes /home/runner/work/pack/pack/packages/document-schema/model-types
 > monorepo-transpile -f esm -m types -t node
 
 👍

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @palantir/pack.document-schema.model-types@0.7.0 typecheck /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.8.0 typecheck /home/runner/work/pack/pack/packages/document-schema/model-types
 > tsc --noEmit --emitDeclarationOnly false
 

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @palantir/pack.document-schema.model-types
 
+## 0.8.0
+
+### Minor Changes
+
+- 2b00422: Add 'gen-types' command, along with scope, metadata and manifest generators
+- 222e157: Wire in lens upgrade registry to reads in the yjs layer
+- ad7a355: Add UpgradeLens utilities
+- 792a1b0: Add new 'gen-types' command, direct from TS schema to Versioned SDK Types.
+
 ## 0.7.0
 
 ### Minor Changes

package/build/cjs/index.d.cts

@@ -35,6 +35,12 @@ interface DocumentMetadata {
     readonly name: string;
     readonly operations?: readonly DocumentOperation[];
     readonly ontologyRid: string;
+    /**
+     * The schema version this document is currently operating at.
+     * All connected clients must read and write at this version.
+     * Set by the backend; only increases (one-way ratchet).
+     */
+    readonly schemaVersion?: number;
     readonly security: DocumentSecurity;
     readonly updatedBy?: string;
     readonly updatedTime?: string;
@@ -222,6 +228,63 @@ interface ActivityEvent {
     readonly isRead: boolean;
 }
 
+/** Type descriptor for a field, enabling recursive lens application. */
+type FieldTypeDescriptor = {
+    kind: "primitive";
+} | {
+    kind: "modelRef";
+    model: string;
+} | {
+    kind: "array";
+    element: FieldTypeDescriptor;
+} | {
+    kind: "map";
+    value: FieldTypeDescriptor;
+} | {
+    kind: "optional";
+    inner: FieldTypeDescriptor;
+};
+interface FieldLensDef {
+    /**
+     * Source field names. `forward` receives only these fields, not the full record.
+     * When empty, the field is additive — only `default` applies and `forward` is never called.
+     */
+    derivedFrom: string[];
+    forward: (oldFields: Record<string, unknown>) => unknown;
+    default?: unknown;
+}
+interface FieldDef {
+    type: FieldTypeDescriptor;
+    default?: unknown;
+}
+interface UpgradeStepDef {
+    name: string;
+    addedInVersion: number;
+    fields: Record<string, FieldLensDef>;
+    removedFields?: string[];
+}
+interface UpgradeRegistry<ModelName extends string = string> {
+    modelName: ModelName;
+    /** All fields in the current schema (not just upgraded ones). Drives recursive lens application on nested types. */
+    allFields: Record<string, FieldDef>;
+    /** Must be in version order — the lens walks them sequentially. */
+    steps: UpgradeStepDef[];
+}
+/**
+ * Upgrade registry for union models. Instead of having its own fields/steps,
+ * a union delegates to the variant's UpgradeRegistry based on the discriminant
+ * value in the data.
+ */
+interface UnionUpgradeRegistry<ModelName extends string = string> {
+    modelName: ModelName;
+    /** The field name used to discriminate between variants. */
+    discriminant: string;
+    /** Maps discriminant values to variant model names in the UpgradeRegistryMap. */
+    variants: Record<string, string>;
+}
+type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
+type UpgradeRegistryMap = Record<string, UpgradeRegistryEntry>;
+
 /**
  * The base type for an application sdk's generated document schema.
  */
@@ -238,6 +301,8 @@ type DocumentState<S extends DocumentSchema> = {
 };
 interface DocumentSchemaMetadata {
     readonly version: number;
+    readonly minSupportedVersion?: number;
+    readonly upgrades?: UpgradeRegistryMap;
 }
 
 declare const PresenceEventDataType: {
@@ -869,4 +934,4 @@ declare namespace PresenceEvents {
   export { PresenceEvents_isArrived as isArrived, PresenceEvents_isCustom as isCustom, PresenceEvents_isDeparted as isDeparted, PresenceEvents_isUnknown as isUnknown };
 }
 
-export { type ActivityEvent, type ActivityEventData, type ActivityEventDataCustom, type ActivityEventDataDocumentCreate, type ActivityEventDataDocumentDescriptionUpdate, type ActivityEventDataDocumentDiscretionarySecurityUpdate, type ActivityEventDataDocumentMandatorySecurityUpdate, type ActivityEventDataDocumentRename, ActivityEventDataType, type ActivityEventDataUnknown, type ActivityEventId, ActivityEvents, type DiscretionaryPrincipal, type DiscretionaryPrincipal_All, type DiscretionaryPrincipal_GroupId, type DiscretionaryPrincipal_UserId, type DocumentId, type DocumentMetadata, type DocumentOperation, type DocumentRef, DocumentRefBrand, type DocumentSchema, type DocumentSchemaMetadata, type DocumentSecurity, type DocumentSecurityDiscretionary, type DocumentSecurityMandatory, type DocumentState, type EditDescription, ExternalRefType, type MediaId, type MediaRef, MediaRefBrand, Metadata, type Model, type ModelData, type ModelMetadata, type ObjectId, type ObjectRef, ObjectRefBrand, type PresenceEvent, type PresenceEventData, type PresenceEventDataArrived, type PresenceEventDataCustom, type PresenceEventDataDeparted, PresenceEventDataType, type PresenceEventDataUnknown, PresenceEvents, type PresencePublishOptions, type PresenceSubscriptionOptions, type RecordCollectionRef, RecordCollectionRefBrand, type RecordId, type RecordModel, type RecordRef, RecordRefBrand, type UnionModel, type Unsubscribe, type UserId, type UserRef, UserRefBrand, type WithMetadata, getMetadata, hasMetadata };
+export { type ActivityEvent, type ActivityEventData, type ActivityEventDataCustom, type ActivityEventDataDocumentCreate, type ActivityEventDataDocumentDescriptionUpdate, type ActivityEventDataDocumentDiscretionarySecurityUpdate, type ActivityEventDataDocumentMandatorySecurityUpdate, type ActivityEventDataDocumentRename, ActivityEventDataType, type ActivityEventDataUnknown, type ActivityEventId, ActivityEvents, type DiscretionaryPrincipal, type DiscretionaryPrincipal_All, type DiscretionaryPrincipal_GroupId, type DiscretionaryPrincipal_UserId, type DocumentId, type DocumentMetadata, type DocumentOperation, type DocumentRef, DocumentRefBrand, type DocumentSchema, type DocumentSchemaMetadata, type DocumentSecurity, type DocumentSecurityDiscretionary, type DocumentSecurityMandatory, type DocumentState, type EditDescription, ExternalRefType, type FieldDef, type FieldLensDef, type FieldTypeDescriptor, type MediaId, type MediaRef, MediaRefBrand, Metadata, type Model, type ModelData, type ModelMetadata, type ObjectId, type ObjectRef, ObjectRefBrand, type PresenceEvent, type PresenceEventData, type PresenceEventDataArrived, type PresenceEventDataCustom, type PresenceEventDataDeparted, PresenceEventDataType, type PresenceEventDataUnknown, PresenceEvents, type PresencePublishOptions, type PresenceSubscriptionOptions, type RecordCollectionRef, RecordCollectionRefBrand, type RecordId, type RecordModel, type RecordRef, RecordRefBrand, type UnionModel, type UnionUpgradeRegistry, type Unsubscribe, type UpgradeRegistry, type UpgradeRegistryEntry, type UpgradeRegistryMap, type UpgradeStepDef, type UserId, type UserRef, UserRefBrand, type WithMetadata, getMetadata, hasMetadata };

package/build/types/index.d.ts

@@ -19,6 +19,7 @@ export type { RecordCollectionRef } from "./types/RecordCollectionRef.js";
 export { RecordRefBrand } from "./types/RecordRef.js";
 export type { RecordId, RecordRef } from "./types/RecordRef.js";
 export type { Unsubscribe } from "./types/Unsubscribe.js";
+export type { FieldDef, FieldLensDef, FieldTypeDescriptor, UnionUpgradeRegistry, UpgradeRegistry, UpgradeRegistryEntry, UpgradeRegistryMap, UpgradeStepDef } from "./types/UpgradeLens.js";
 export { UserRefBrand } from "./types/UserRef.js";
 export type { UserId, UserRef } from "./types/UserRef.js";
 export * as ActivityEvents from "./utils/ActivityEvents.js";

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

@@ -1 +1 @@
-{"mappings":"AAgBA,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,yBACA,iCACA,4CACA,sDACA,kDACA,iCACA,0BACA,uBACK;AACP,cACE,wBACA,4BACA,gCACA,+BACA,kBACA,mBACA,kBACA,+BACA,iCACK;AACP,SAAS,wBAAwB;AACjC,cACE,YACA,aACA,wBACA,mCACK;AACP,cACE,gBACA,wBACA,qBACK;AACP,SAAS,qBAAqB;AAC9B,cAAc,SAAS,gBAAgB;AACvC,SAAS,aAAa,aAAa,gBAAgB;AACnD,cAAc,oBAAoB;AAClC,SAAS,uBAAuB;AAChC,cACE,iBACA,OACA,WACA,eACA,aACA,kBACK;AACP,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,0BACA,yBACA,2BACA,gCACK;AACP,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,cAAc,mBAAmB;AACjC,SAAS,oBAAoB;AAC7B,cAAc,QAAQ,eAAe;AACrC,YAAY,oBAAoB;AAChC,YAAY,oBAAoB","names":[],"sources":["../../src/index.ts"],"version":3,"file":"index.d.ts"}
+{"mappings":"AAgBA,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,yBACA,iCACA,4CACA,sDACA,kDACA,iCACA,0BACA,uBACK;AACP,cACE,wBACA,4BACA,gCACA,+BACA,kBACA,mBACA,kBACA,+BACA,iCACK;AACP,SAAS,wBAAwB;AACjC,cACE,YACA,aACA,wBACA,mCACK;AACP,cACE,gBACA,wBACA,qBACK;AACP,SAAS,qBAAqB;AAC9B,cAAc,SAAS,gBAAgB;AACvC,SAAS,aAAa,aAAa,gBAAgB;AACnD,cAAc,oBAAoB;AAClC,SAAS,uBAAuB;AAChC,cACE,iBACA,OACA,WACA,eACA,aACA,kBACK;AACP,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,0BACA,yBACA,2BACA,gCACK;AACP,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,cAAc,mBAAmB;AACjC,cACE,UACA,cACA,qBACA,sBACA,iBACA,sBACA,oBACA,sBACK;AACP,SAAS,oBAAoB;AAC7B,cAAc,QAAQ,eAAe;AACrC,YAAY,oBAAoB;AAChC,YAAY,oBAAoB","names":[],"sources":["../../src/index.ts"],"version":3,"file":"index.d.ts"}

package/build/types/types/DocumentMetadata.d.ts

@@ -32,6 +32,12 @@ export interface DocumentMetadata {
 	readonly name: string;
 	readonly operations?: readonly DocumentOperation[];
 	readonly ontologyRid: string;
+	/**
+	* The schema version this document is currently operating at.
+	* All connected clients must read and write at this version.
+	* Set by the backend; only increases (one-way ratchet).
+	*/
+	readonly schemaVersion?: number;
 	readonly security: DocumentSecurity;
 	readonly updatedBy?: string;
 	readonly updatedTime?: string;

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

@@ -1 +1 @@
-{"mappings":"AAgBA,iBAAiB,2BAA2B;CAC1C,QAAQ;;AAEV,iBAAiB,8BAA8B;CAC7C,QAAQ;CACR;;AAEF,iBAAiB,+BAA+B;CAC9C;CACA,QAAQ;;AAGV,YAAY,yBACR,6BACA,iCACA;AAEJ,iBAAiB,8BAA8B;UACpC,mBAAmB;UACnB,kBAAkB;UAClB,mBAAmB;;AAG9B,iBAAiB,0BAA0B;UAChC;UACA;;AAGX,iBAAiB,iBAAiB;UACvB,eAAe;UACf,WAAW;;AAGtB,YAAY,oBAAoB,SAAS,SAAS,QAAQ;AAE1D,iBAAiB,iBAAiB;UACvB;UACA;UACA;UACA;UACA;UACA,sBAAsB;UACtB;UACA,UAAU;UACV;UACA","names":[],"sources":["../../../src/types/DocumentMetadata.ts"],"version":3,"file":"DocumentMetadata.d.ts"}
+{"mappings":"AAgBA,iBAAiB,2BAA2B;CAC1C,QAAQ;;AAEV,iBAAiB,8BAA8B;CAC7C,QAAQ;CACR;;AAEF,iBAAiB,+BAA+B;CAC9C;CACA,QAAQ;;AAGV,YAAY,yBACR,6BACA,iCACA;AAEJ,iBAAiB,8BAA8B;UACpC,mBAAmB;UACnB,kBAAkB;UAClB,mBAAmB;;AAG9B,iBAAiB,0BAA0B;UAChC;UACA;;AAGX,iBAAiB,iBAAiB;UACvB,eAAe;UACf,WAAW;;AAGtB,YAAY,oBAAoB,SAAS,SAAS,QAAQ;AAE1D,iBAAiB,iBAAiB;UACvB;UACA;UACA;UACA;UACA;UACA,sBAAsB;UACtB;;;;;;UAMA;UACA,UAAU;UACV;UACA","names":[],"sources":["../../../src/types/DocumentMetadata.ts"],"version":3,"file":"DocumentMetadata.d.ts"}

package/build/types/types/DocumentSchema.d.ts

@@ -1,5 +1,6 @@
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
+import type { UpgradeRegistryMap } from "./UpgradeLens.js";
 /**
 * The base type for an application sdk's generated document schema.
 */
@@ -14,4 +15,6 @@ export type DocumentState<S extends DocumentSchema> = { readonly [K in Exclude<k
 } };
 export interface DocumentSchemaMetadata {
 	readonly version: number;
+	readonly minSupportedVersion?: number;
+	readonly upgrades?: UpgradeRegistryMap;
 }

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;;;;AAKtC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;;;;AAMhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}
+{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;AACtC,cAAc,0BAA0B;;;;AAKxC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;;;;AAMhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B;UACA;UACA,WAAW","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}

package/build/types/types/UpgradeLens.d.ts

@@ -0,0 +1,56 @@
+/** Type descriptor for a field, enabling recursive lens application. */
+export type FieldTypeDescriptor = {
+	kind: "primitive";
+} | {
+	kind: "modelRef";
+	model: string;
+} | {
+	kind: "array";
+	element: FieldTypeDescriptor;
+} | {
+	kind: "map";
+	value: FieldTypeDescriptor;
+} | {
+	kind: "optional";
+	inner: FieldTypeDescriptor;
+};
+export interface FieldLensDef {
+	/**
+	* Source field names. `forward` receives only these fields, not the full record.
+	* When empty, the field is additive — only `default` applies and `forward` is never called.
+	*/
+	derivedFrom: string[];
+	forward: (oldFields: Record<string, unknown>) => unknown;
+	default?: unknown;
+}
+export interface FieldDef {
+	type: FieldTypeDescriptor;
+	default?: unknown;
+}
+export interface UpgradeStepDef {
+	name: string;
+	addedInVersion: number;
+	fields: Record<string, FieldLensDef>;
+	removedFields?: string[];
+}
+export interface UpgradeRegistry<ModelName extends string = string> {
+	modelName: ModelName;
+	/** All fields in the current schema (not just upgraded ones). Drives recursive lens application on nested types. */
+	allFields: Record<string, FieldDef>;
+	/** Must be in version order — the lens walks them sequentially. */
+	steps: UpgradeStepDef[];
+}
+/**
+* Upgrade registry for union models. Instead of having its own fields/steps,
+* a union delegates to the variant's UpgradeRegistry based on the discriminant
+* value in the data.
+*/
+export interface UnionUpgradeRegistry<ModelName extends string = string> {
+	modelName: ModelName;
+	/** The field name used to discriminate between variants. */
+	discriminant: string;
+	/** Maps discriminant values to variant model names in the UpgradeRegistryMap. */
+	variants: Record<string, string>;
+}
+export type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
+export type UpgradeRegistryMap = Record<string, UpgradeRegistryEntry>;

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

@@ -0,0 +1 @@
+{"mappings":";AAiBA,YAAY,sBACR;CAAE,MAAM;IACR;CAAE,MAAM;CAAY;IACpB;CAAE,MAAM;CAAS,SAAS;IAC1B;CAAE,MAAM;CAAO,OAAO;IACtB;CAAE,MAAM;CAAY,OAAO;;AAE/B,iBAAiB,aAAa;;;;;CAK5B;CACA,UAAU,WAAW;CACrB;;AAGF,iBAAiB,SAAS;CACxB,MAAM;CACN;;AAGF,iBAAiB,eAAe;CAC9B;CACA;CACA,QAAQ,eAAe;CACvB;;AAGF,iBAAiB,gBAAgB,mCAAmC;CAClE,WAAW;;CAEX,WAAW,eAAe;;CAE1B,OAAO;;;;;;;AAQT,iBAAiB,qBAAqB,mCAAmC;CACvE,WAAW;;CAEX;;CAEA,UAAU;;AAGZ,YAAY,uBAAuB,kBAAkB;AAErD,YAAY,qBAAqB,eAAe","names":[],"sources":["../../../src/types/UpgradeLens.ts"],"version":3,"file":"UpgradeLens.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.document-schema.model-types",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -79,6 +79,16 @@ export type { RecordCollectionRef } from "./types/RecordCollectionRef.js";
 export { RecordRefBrand } from "./types/RecordRef.js";
 export type { RecordId, RecordRef } from "./types/RecordRef.js";
 export type { Unsubscribe } from "./types/Unsubscribe.js";
+export type {
+  FieldDef,
+  FieldLensDef,
+  FieldTypeDescriptor,
+  UnionUpgradeRegistry,
+  UpgradeRegistry,
+  UpgradeRegistryEntry,
+  UpgradeRegistryMap,
+  UpgradeStepDef,
+} from "./types/UpgradeLens.js";
 export { UserRefBrand } from "./types/UserRef.js";
 export type { UserId, UserRef } from "./types/UserRef.js";
 export * as ActivityEvents from "./utils/ActivityEvents.js";

package/src/types/DocumentMetadata.ts

@@ -57,6 +57,12 @@ export interface DocumentMetadata {
   readonly name: string;
   readonly operations?: readonly DocumentOperation[];
   readonly ontologyRid: string;
+  /**
+   * The schema version this document is currently operating at.
+   * All connected clients must read and write at this version.
+   * Set by the backend; only increases (one-way ratchet).
+   */
+  readonly schemaVersion?: number;
   readonly security: DocumentSecurity;
   readonly updatedBy?: string;
   readonly updatedTime?: string;

package/src/types/DocumentSchema.ts

@@ -16,6 +16,7 @@
 
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
+import type { UpgradeRegistryMap } from "./UpgradeLens.js";
 
 /**
  * The base type for an application sdk's generated document schema.
@@ -33,4 +34,6 @@ export type DocumentState<S extends DocumentSchema> = {
 
 export interface DocumentSchemaMetadata {
   readonly version: number;
+  readonly minSupportedVersion?: number;
+  readonly upgrades?: UpgradeRegistryMap;
 }

package/src/types/UpgradeLens.ts

@@ -0,0 +1,70 @@
+/*
+ * 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.
+ */
+
+/** Type descriptor for a field, enabling recursive lens application. */
+export type FieldTypeDescriptor =
+  | { kind: "primitive" }
+  | { kind: "modelRef"; model: string }
+  | { kind: "array"; element: FieldTypeDescriptor }
+  | { kind: "map"; value: FieldTypeDescriptor }
+  | { kind: "optional"; inner: FieldTypeDescriptor };
+
+export interface FieldLensDef {
+  /**
+   * Source field names. `forward` receives only these fields, not the full record.
+   * When empty, the field is additive — only `default` applies and `forward` is never called.
+   */
+  derivedFrom: string[];
+  forward: (oldFields: Record<string, unknown>) => unknown;
+  default?: unknown;
+}
+
+export interface FieldDef {
+  type: FieldTypeDescriptor;
+  default?: unknown;
+}
+
+export interface UpgradeStepDef {
+  name: string;
+  addedInVersion: number;
+  fields: Record<string, FieldLensDef>;
+  removedFields?: string[];
+}
+
+export interface UpgradeRegistry<ModelName extends string = string> {
+  modelName: ModelName;
+  /** All fields in the current schema (not just upgraded ones). Drives recursive lens application on nested types. */
+  allFields: Record<string, FieldDef>;
+  /** Must be in version order — the lens walks them sequentially. */
+  steps: UpgradeStepDef[];
+}
+
+/**
+ * Upgrade registry for union models. Instead of having its own fields/steps,
+ * a union delegates to the variant's UpgradeRegistry based on the discriminant
+ * value in the data.
+ */
+export interface UnionUpgradeRegistry<ModelName extends string = string> {
+  modelName: ModelName;
+  /** The field name used to discriminate between variants. */
+  discriminant: string;
+  /** Maps discriminant values to variant model names in the UpgradeRegistryMap. */
+  variants: Record<string, string>;
+}
+
+export type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
+
+export type UpgradeRegistryMap = Record<string, UpgradeRegistryEntry>;