@palantir/pack.document-schema.model-types 0.31.0 → 0.33.0

package/build/types/index.d.ts

@@ -1,5 +1,5 @@
 export { ActivityEventDataType } from "./types/ActivityEvent.js";
-export type { ActivityEvent, ActivityEventData, ActivityEventDataCustom, ActivityEventDataDocumentCreate, ActivityEventDataDocumentDescriptionUpdate, ActivityEventDataDocumentDiscretionarySecurityUpdate, ActivityEventDataDocumentMandatorySecurityUpdate, ActivityEventDataDocumentRename, ActivityEventDataUnknown, ActivityEventId } from "./types/ActivityEvent.js";
+export type { ActivityEvent, ActivityEventData, ActivityEventDataCustom, ActivityEventDataDocumentCreate, ActivityEventDataDocumentDescriptionUpdate, ActivityEventDataDocumentDiscretionarySecurityUpdate, ActivityEventDataDocumentMandatorySecurityUpdate, ActivityEventDataDocumentRename, ActivityEventDataPublishedVersionCreate, ActivityEventDataPublishedVersionDelete, ActivityEventDataUnknown, ActivityEventId } from "./types/ActivityEvent.js";
 export { ChannelErrorCode, toChannelError, toUnknownChannelError } from "./types/ChannelError.js";
 export type { ChannelError } from "./types/ChannelError.js";
 export type { DiscretionaryPrincipal, DiscretionaryPrincipal_All, DiscretionaryPrincipal_GroupId, DiscretionaryPrincipal_UserId, DocumentMetadata, DocumentOperation, DocumentSecurity, DocumentSecurityDiscretionary, DocumentSecurityMandatory } from "./types/DocumentMetadata.js";
@@ -24,6 +24,8 @@ export type { RecordId, RecordRef } from "./types/RecordRef.js";
 export { RecordInvalidError } from "./types/RecordValidation.js";
 export type { RecordValidationError, RecordValidationIssue } from "./types/RecordValidation.js";
 export type { ResourceRid } from "./types/ResourceRid.js";
+export { UNKNOWN_UNION_VARIANT } from "./types/UnknownUnionVariant.js";
+export type { UnknownUnionVariant } from "./types/UnknownUnionVariant.js";
 export type { Unsubscribe } from "./types/Unsubscribe.js";
 export type { FieldDef, FieldLensDef, FieldTypeDescriptor, UnionUpgradeRegistry, UpgradeFns, UpgradeRegistry, UpgradeRegistryEntry, UpgradeRegistryMap, UpgradeStepDef } from "./types/UpgradeLens.js";
 export { UserRefBrand } from "./types/UserRef.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,SAAS,kBAAkB,gBAAgB,6BAA6B;AACxE,cAAc,oBAAoB;AAClC,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,cACE,kBACA,6BACA,0BACK;AACP,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,0BAA0B;AACnC,cAAc,uBAAuB,6BAA6B;AAClE,cAAc,mBAAmB;AACjC,cAAc,mBAAmB;AACjC,cACE,UACA,cACA,qBACA,sBACA,YACA,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"}
+{"mappings":"AAgBA,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,yBACA,iCACA,4CACA,sDACA,kDACA,iCACA,yCACA,yCACA,0BACA,uBACK;AACP,SAAS,kBAAkB,gBAAgB,6BAA6B;AACxE,cAAc,oBAAoB;AAClC,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,cACE,kBACA,6BACA,0BACK;AACP,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,0BAA0B;AACnC,cAAc,uBAAuB,6BAA6B;AAClE,cAAc,mBAAmB;AACjC,SAAS,6BAA6B;AACtC,cAAc,2BAA2B;AACzC,cAAc,mBAAmB;AACjC,cACE,UACA,cACA,qBACA,sBACA,YACA,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/ActivityEvent.d.ts

@@ -1,6 +1,7 @@
 import type { Flavored } from "@palantir/pack.core";
 import type { DocumentSecurityDiscretionary, DocumentSecurityMandatory } from "./DocumentMetadata.js";
 import type { Model, ModelData } from "./Model.js";
+import type { PublishedVersionId } from "./PublishedVersion.js";
 import type { UserId } from "./UserRef.js";
 export type ActivityEventId = Flavored<"pack:EventId">;
 export declare const ActivityEventDataType: {
@@ -10,6 +11,8 @@ export declare const ActivityEventDataType: {
 	readonly DOCUMENT_RENAME: "documentRename";
 	readonly DOCUMENT_MANDATORY_SECURITY_UPDATE: "documentMandatorySecurityUpdate";
 	readonly DOCUMENT_DISCRETIONARY_SECURITY_UPDATE: "documentDiscretionarySecurityUpdate";
+	readonly PUBLISHED_VERSION_CREATE: "publishedVersionCreate";
+	readonly PUBLISHED_VERSION_DELETE: "publishedVersionDelete";
 	readonly UNKNOWN: "unknown";
 };
 /**
@@ -86,6 +89,24 @@ export interface ActivityEventDataDocumentMandatorySecurityUpdate {
 	readonly newMarkings: readonly string[];
 }
 /**
+* Activity event emitted when a published version of a document is created.
+*/
+export interface ActivityEventDataPublishedVersionCreate {
+	readonly type: typeof ActivityEventDataType.PUBLISHED_VERSION_CREATE;
+	readonly publishedVersionId: PublishedVersionId;
+	readonly name?: string;
+	readonly description?: string;
+}
+/**
+* Activity event emitted when a published version of a document is deleted.
+*/
+export interface ActivityEventDataPublishedVersionDelete {
+	readonly type: typeof ActivityEventDataType.PUBLISHED_VERSION_DELETE;
+	readonly publishedVersionId: PublishedVersionId;
+	readonly name?: string;
+	readonly description?: string;
+}
+/**
 * Fallback for unrecognized activity event types.
 *
 * This allows some flexibility with new event types added to the platform.
@@ -98,7 +119,7 @@ export interface ActivityEventDataUnknown {
 	readonly rawType: string;
 	readonly rawData: unknown;
 }
-export type ActivityEventData = ActivityEventDataCustom | ActivityEventDataDocumentCreate | ActivityEventDataDocumentDescriptionUpdate | ActivityEventDataDocumentRename | ActivityEventDataDocumentMandatorySecurityUpdate | ActivityEventDataDocumentDiscretionarySecurityUpdate | ActivityEventDataUnknown;
+export type ActivityEventData = ActivityEventDataCustom | ActivityEventDataDocumentCreate | ActivityEventDataDocumentDescriptionUpdate | ActivityEventDataDocumentRename | ActivityEventDataDocumentMandatorySecurityUpdate | ActivityEventDataDocumentDiscretionarySecurityUpdate | ActivityEventDataPublishedVersionCreate | ActivityEventDataPublishedVersionDelete | ActivityEventDataUnknown;
 /**
 * An event representing an activity that has occurred on a document. This
 * includes standard document events as well as custom application-specific

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cACE,+BACA,iCACK;AACP,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,YAAY,kBAAkB,SAAS;AAEvC,OAAO,cAAM;UACX,cAAc;UACd,iBAAiB;UACjB,6BAA6B;UAC7B,iBAAiB;UACjB,oCAAoC;UACpC,wCAAwC;UACxC,SAAS;;;;;;;;;;;;;;;;;;;;;;;AAwBX,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,OAAO;UACP;UACA;UACA,MAAM,UAAU;;;;;AAM3B,iBAAiB,gCAAgC;UACtC,aAAa,sBAAsB;UACnC,0BAA0B;UAC1B;;;;;AAMX,iBAAiB,gCAAgC;UACtC,aAAa,sBAAsB;UACnC;UACA;;;;;AAMX,iBAAiB,2CAA2C;UACjD,aAAa,sBAAsB;UACnC;;;;;UAKA;;;;;AAMX,iBAAiB,qDAAqD;UAC3D,aAAa,sBAAsB;UACnC,eAAe,kBAAkB;UACjC,gCAAgC;UAChC,0BAA0B;;;;;AAMrC,iBAAiB,iDAAiD;UACvD,aAAa,sBAAsB;UACnC;UACA;;;;;;;;;;AAWX,iBAAiB,yBAAyB;UAC/B,aAAa,sBAAsB;UACnC;UACA;;AAGX,YAAY,oBACR,0BACA,kCACA,6CACA,kCACA,mDACA,uDACA;;;;;;;;AASJ,iBAAiB,cAAc;;UAEpB;UACA,WAAW;UACX;UACA,WAAW;UACX,SAAS;UACT","names":[],"sources":["../../../src/types/ActivityEvent.ts"],"version":3,"file":"ActivityEvent.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cACE,+BACA,iCACK;AACP,cAAc,OAAO,iBAAiB;AACtC,cAAc,0BAA0B;AACxC,cAAc,cAAc;AAE5B,YAAY,kBAAkB,SAAS;AAEvC,OAAO,cAAM;UACX,cAAc;UACd,iBAAiB;UACjB,6BAA6B;UAC7B,iBAAiB;UACjB,oCAAoC;UACpC,wCAAwC;UACxC,0BAA0B;UAC1B,0BAA0B;UAC1B,SAAS;;;;;;;;;;;;;;;;;;;;;;;AAwBX,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,OAAO;UACP;UACA;UACA,MAAM,UAAU;;;;;AAM3B,iBAAiB,gCAAgC;UACtC,aAAa,sBAAsB;UACnC,0BAA0B;UAC1B;;;;;AAMX,iBAAiB,gCAAgC;UACtC,aAAa,sBAAsB;UACnC;UACA;;;;;AAMX,iBAAiB,2CAA2C;UACjD,aAAa,sBAAsB;UACnC;;;;;UAKA;;;;;AAMX,iBAAiB,qDAAqD;UAC3D,aAAa,sBAAsB;UACnC,eAAe,kBAAkB;UACjC,gCAAgC;UAChC,0BAA0B;;;;;AAMrC,iBAAiB,iDAAiD;UACvD,aAAa,sBAAsB;UACnC;UACA;;;;;AAMX,iBAAiB,wCAAwC;UAC9C,aAAa,sBAAsB;UACnC,oBAAoB;UACpB;UACA;;;;;AAMX,iBAAiB,wCAAwC;UAC9C,aAAa,sBAAsB;UACnC,oBAAoB;UACpB;UACA;;;;;;;;;;AAWX,iBAAiB,yBAAyB;UAC/B,aAAa,sBAAsB;UACnC;UACA;;AAGX,YAAY,oBACR,0BACA,kCACA,6CACA,kCACA,mDACA,uDACA,0CACA,0CACA;;;;;;;;AASJ,iBAAiB,cAAc;;UAEpB;UACA,WAAW;UACX;UACA,WAAW;UACX,SAAS;UACT","names":[],"sources":["../../../src/types/ActivityEvent.ts"],"version":3,"file":"ActivityEvent.d.ts"}

package/build/types/types/UnknownUnionVariant.d.ts

@@ -0,0 +1,10 @@
+/** The discriminant value of a union variant this SDK doesn't know. Reserved: no real variant can use it. */
+export declare const UNKNOWN_UNION_VARIANT = "unknown";
+/**
+* A union value whose variant this SDK doesn't know, e.g. one added by a newer version of the app.
+* Every generated union includes this case. `rawValue` is the stored value, kept as-is: saving a
+* record or list that contains it writes it back unchanged.
+*/
+export type UnknownUnionVariant<D extends string> = { readonly [K in D] : typeof UNKNOWN_UNION_VARIANT } & {
+	readonly rawValue?: unknown;
+};

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

@@ -0,0 +1 @@
+{"mappings":";AAiBA,OAAO,cAAM,wBAAwB;;;;;;AAOrC,YAAY,oBAAoB,gCAChB,KAAK,YAAW,0BAC5B;UAAW","names":[],"sources":["../../../src/types/UnknownUnionVariant.ts"],"version":3,"file":"UnknownUnionVariant.d.ts"}

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

@@ -28,8 +28,10 @@ export interface FieldDef {
 	addedInVersion?: number;
 }
 export interface UpgradeStepDef {
-	/** Schema version this step upgrades to. Unique within a model's chain. */
+	/** Major version that added this step's fields, e.g. 3 for a step added in 3.2. */
 	addedInVersion: number;
+	/** Minor version that added this step's fields, e.g. 2 for 3.2. Absent means 0. */
+	addedInMinorVersion?: number;
 	fields: Record<string, FieldLensDef>;
 	removedFields?: string[];
 }
@@ -58,7 +60,8 @@ export type UpgradeRegistryMap = Record<string, UpgradeRegistryEntry>;
 * Runtime-supplied collection of forward upgrade functions. The application
 * passes a `DocumentUpgradeFns` value to the generated `DocumentModel(...)`
 * factory at boot; the factory installs it on the schema's metadata under
-* this loose shape: `fns[modelName][\`v${addedInVersion}\`][fieldName] -> fn`.
+* this loose shape: `fns[modelName][stepKey][fieldName] -> fn`, where `stepKey` is
+* `v2` for version 2.0 and `v2_1` for version 2.1.
 *
 * The generated `DocumentUpgradeFns` interface is a precisely-typed refinement
 * of this shape; both `BaseYjsDocumentService` and `applyReadLens` read from

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

@@ -1 +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;;;;;;;CAO5B;;AAGF,iBAAiB,SAAS;CACxB,MAAM;CACN;;AAGF,iBAAiB,eAAe;;CAE9B;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;;;;;;;;;;;;;;AAehD,YAAY,aAAa,eAEvB,eAAe,gBAAgB","names":[],"sources":["../../../src/types/UpgradeLens.ts"],"version":3,"file":"UpgradeLens.d.ts"}
+{"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;;;;;;;CAO5B;;AAGF,iBAAiB,SAAS;CACxB,MAAM;CACN;;AAGF,iBAAiB,eAAe;;CAE9B;;CAEA;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;;;;;;;;;;;;;;;AAgBhD,YAAY,aAAa,eAEvB,eAAe,gBAAgB","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.31.0",
+  "version": "0.33.0",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@palantir/pack.core": "~0.31.0"
+    "@palantir/pack.core": "~0.33.0"
   },
   "peerDependencies": {
     "zod": "^4.1.7"

package/src/index.ts

@@ -24,6 +24,8 @@ export type {
   ActivityEventDataDocumentDiscretionarySecurityUpdate,
   ActivityEventDataDocumentMandatorySecurityUpdate,
   ActivityEventDataDocumentRename,
+  ActivityEventDataPublishedVersionCreate,
+  ActivityEventDataPublishedVersionDelete,
   ActivityEventDataUnknown,
   ActivityEventId,
 } from "./types/ActivityEvent.js";
@@ -88,6 +90,8 @@ export type { RecordId, RecordRef } from "./types/RecordRef.js";
 export { RecordInvalidError } from "./types/RecordValidation.js";
 export type { RecordValidationError, RecordValidationIssue } from "./types/RecordValidation.js";
 export type { ResourceRid } from "./types/ResourceRid.js";
+export { UNKNOWN_UNION_VARIANT } from "./types/UnknownUnionVariant.js";
+export type { UnknownUnionVariant } from "./types/UnknownUnionVariant.js";
 export type { Unsubscribe } from "./types/Unsubscribe.js";
 export type {
   FieldDef,

package/src/types/ActivityEvent.ts

@@ -20,6 +20,7 @@ import type {
   DocumentSecurityMandatory,
 } from "./DocumentMetadata.js";
 import type { Model, ModelData } from "./Model.js";
+import type { PublishedVersionId } from "./PublishedVersion.js";
 import type { UserId } from "./UserRef.js";
 
 export type ActivityEventId = Flavored<"pack:EventId">;
@@ -31,6 +32,8 @@ export const ActivityEventDataType = {
   DOCUMENT_RENAME: "documentRename",
   DOCUMENT_MANDATORY_SECURITY_UPDATE: "documentMandatorySecurityUpdate",
   DOCUMENT_DISCRETIONARY_SECURITY_UPDATE: "documentDiscretionarySecurityUpdate",
+  PUBLISHED_VERSION_CREATE: "publishedVersionCreate",
+  PUBLISHED_VERSION_DELETE: "publishedVersionDelete",
   UNKNOWN: "unknown",
 } as const;
 
@@ -113,6 +116,26 @@ export interface ActivityEventDataDocumentMandatorySecurityUpdate {
   readonly newMarkings: readonly string[];
 }
 
+/**
+ * Activity event emitted when a published version of a document is created.
+ */
+export interface ActivityEventDataPublishedVersionCreate {
+  readonly type: typeof ActivityEventDataType.PUBLISHED_VERSION_CREATE;
+  readonly publishedVersionId: PublishedVersionId;
+  readonly name?: string;
+  readonly description?: string;
+}
+
+/**
+ * Activity event emitted when a published version of a document is deleted.
+ */
+export interface ActivityEventDataPublishedVersionDelete {
+  readonly type: typeof ActivityEventDataType.PUBLISHED_VERSION_DELETE;
+  readonly publishedVersionId: PublishedVersionId;
+  readonly name?: string;
+  readonly description?: string;
+}
+
 /**
  * Fallback for unrecognized activity event types.
  *
@@ -134,6 +157,8 @@ export type ActivityEventData =
   | ActivityEventDataDocumentRename
   | ActivityEventDataDocumentMandatorySecurityUpdate
   | ActivityEventDataDocumentDiscretionarySecurityUpdate
+  | ActivityEventDataPublishedVersionCreate
+  | ActivityEventDataPublishedVersionDelete
   | ActivityEventDataUnknown;
 
 /**

package/src/types/UnknownUnionVariant.ts

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+
+/** The discriminant value of a union variant this SDK doesn't know. Reserved: no real variant can use it. */
+export const UNKNOWN_UNION_VARIANT = "unknown";
+
+/**
+ * A union value whose variant this SDK doesn't know, e.g. one added by a newer version of the app.
+ * Every generated union includes this case. `rawValue` is the stored value, kept as-is: saving a
+ * record or list that contains it writes it back unchanged.
+ */
+export type UnknownUnionVariant<D extends string> =
+  & { readonly [K in D]: typeof UNKNOWN_UNION_VARIANT }
+  & { readonly rawValue?: unknown };

package/src/types/UpgradeLens.ts

@@ -38,8 +38,10 @@ export interface FieldDef {
 }
 
 export interface UpgradeStepDef {
-  /** Schema version this step upgrades to. Unique within a model's chain. */
+  /** Major version that added this step's fields, e.g. 3 for a step added in 3.2. */
   addedInVersion: number;
+  /** Minor version that added this step's fields, e.g. 2 for 3.2. Absent means 0. */
+  addedInMinorVersion?: number;
   fields: Record<string, FieldLensDef>;
   removedFields?: string[];
 }
@@ -73,7 +75,8 @@ export type UpgradeRegistryMap = Record<string, UpgradeRegistryEntry>;
  * Runtime-supplied collection of forward upgrade functions. The application
  * passes a `DocumentUpgradeFns` value to the generated `DocumentModel(...)`
  * factory at boot; the factory installs it on the schema's metadata under
- * this loose shape: `fns[modelName][\`v${addedInVersion}\`][fieldName] -> fn`.
+ * this loose shape: `fns[modelName][stepKey][fieldName] -> fn`, where `stepKey` is
+ * `v2` for version 2.0 and `v2_1` for version 2.1.
  *
  * The generated `DocumentUpgradeFns` interface is a precisely-typed refinement
  * of this shape; both `BaseYjsDocumentService` and `applyReadLens` read from