@palantir/pack.document-schema.model-types 0.9.0 → 0.11.0

package/.turbo/turbo-lint.log

@@ -1,4 +1,4 @@
 
-> @palantir/pack.document-schema.model-types@0.9.0 lint /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.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,6 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.9.0 transpileBrowser /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.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,6 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.9.0 transpileCjs /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.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,6 +1,5 @@
 
-> @palantir/pack.document-schema.model-types@0.9.0 transpileEsm /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.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.9.0 transpileTypes /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.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.9.0 typecheck /home/runner/work/pack/pack/packages/document-schema/model-types
+> @palantir/pack.document-schema.model-types@0.11.0 typecheck /home/runner/work/pack/pack/packages/document-schema/model-types
 > tsc --noEmit --emitDeclarationOnly false
 

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @palantir/pack.document-schema.model-types
 
+## 0.11.0
+
+### Minor Changes
+
+- e540eba: Move upgrade forward functions out of the schema/IR into a typed UpgradeFns table that apps supply to the generated DocumentModel(...) factory at boot, eliminating Function.toString() source-splicing and enforcing exhaustive upgrade function coverage at compile time.
+
+## 0.10.0
+
+### Patch Changes
+
+- Updated dependencies [597bb0c]
+  - @palantir/pack.core@0.3.0
+
 ## 0.9.0
 
 ### Minor Changes

package/build/cjs/index.d.cts

@@ -228,6 +228,15 @@ interface ActivityEvent {
     readonly isRead: boolean;
 }
 
+/**
+ * Any value losslessly representable as JSON. Used to constrain literal defaults
+ * declared in the schema/IR — anything not expressible as JSON (functions,
+ * `Date`, `RegExp`, class instances, `undefined`) is rejected at the type level.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
 /** Type descriptor for a field, enabling recursive lens application. */
 type FieldTypeDescriptor = {
     kind: "primitive";
@@ -246,19 +255,19 @@ type 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.
+     * Source field names. When empty, the field is additive — only `default` applies and no
+     * forward function is invoked.
      */
     derivedFrom: string[];
-    forward: (oldFields: Record<string, unknown>) => unknown;
-    default?: unknown;
+    /** Literal JSON only — validated at schema build time. Used when no source data exists. */
+    default?: JsonValue;
 }
 interface FieldDef {
     type: FieldTypeDescriptor;
     default?: unknown;
 }
 interface UpgradeStepDef {
-    name: string;
+    /** Schema version this step upgrades to. Unique within a model's chain. */
     addedInVersion: number;
     fields: Record<string, FieldLensDef>;
     removedFields?: string[];
@@ -284,6 +293,20 @@ interface UnionUpgradeRegistry<ModelName extends string = string> {
 }
 type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
 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`.
+ *
+ * The generated `DocumentUpgradeFns` interface is a precisely-typed refinement
+ * of this shape; both `BaseYjsDocumentService` and `applyReadLens` read from
+ * it via this loose type.
+ *
+ * Paired with `UpgradeRegistry`: the registry is the structural spec (WHEN to
+ * upgrade and from which fields), `UpgradeFns` provides the implementations.
+ */
+type UpgradeFns = Record<string, Record<string, Record<string, (oldFields: any) => any>>>;
 
 /**
  * The base type for an application sdk's generated document schema.
@@ -303,6 +326,13 @@ interface DocumentSchemaMetadata {
     readonly version: number;
     readonly minSupportedVersion?: number;
     readonly upgrades?: UpgradeRegistryMap;
+    /**
+     * Typed forward functions, supplied by the app at boot via the generated
+     * `DocumentModel(...)` factory. Populated when the schema has any derived
+     * fields; absent for schemas that don't need any (single-version or purely
+     * additive across versions). Paired with `upgrades` (the structural spec).
+     */
+    readonly upgradeFns?: UpgradeFns;
 }
 
 declare const PresenceEventDataType: {
@@ -934,4 +964,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 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 };
+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 JsonValue, 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 UpgradeFns, type UpgradeRegistry, type UpgradeRegistryEntry, type UpgradeRegistryMap, type UpgradeStepDef, type UserId, type UserRef, UserRefBrand, type WithMetadata, getMetadata, hasMetadata };

package/build/types/index.d.ts

@@ -4,6 +4,7 @@ export type { DiscretionaryPrincipal, DiscretionaryPrincipal_All, DiscretionaryP
 export { DocumentRefBrand } from "./types/DocumentRef.js";
 export type { DocumentId, DocumentRef, PresencePublishOptions, PresenceSubscriptionOptions } from "./types/DocumentRef.js";
 export type { DocumentSchema, DocumentSchemaMetadata, DocumentState } from "./types/DocumentSchema.js";
+export type { JsonValue } from "./types/JsonValue.js";
 export { MediaRefBrand } from "./types/MediaRef.js";
 export type { MediaId, MediaRef } from "./types/MediaRef.js";
 export { getMetadata, hasMetadata, Metadata } from "./types/Metadata.js";
@@ -19,7 +20,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 type { FieldDef, FieldLensDef, FieldTypeDescriptor, UnionUpgradeRegistry, UpgradeFns, 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,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"}
+{"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,cAAc,iBAAiB;AAC/B,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,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/DocumentSchema.d.ts

@@ -1,6 +1,6 @@
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
-import type { UpgradeRegistryMap } from "./UpgradeLens.js";
+import type { UpgradeFns, UpgradeRegistryMap } from "./UpgradeLens.js";
 /**
 * The base type for an application sdk's generated document schema.
 */
@@ -17,4 +17,11 @@ export interface DocumentSchemaMetadata {
 	readonly version: number;
 	readonly minSupportedVersion?: number;
 	readonly upgrades?: UpgradeRegistryMap;
+	/**
+	* Typed forward functions, supplied by the app at boot via the generated
+	* `DocumentModel(...)` factory. Populated when the schema has any derived
+	* fields; absent for schemas that don't need any (single-version or purely
+	* additive across versions). Paired with `upgrades` (the structural spec).
+	*/
+	readonly upgradeFns?: UpgradeFns;
 }

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

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

package/build/types/types/JsonValue.d.ts

@@ -0,0 +1,8 @@
+/**
+* Any value losslessly representable as JSON. Used to constrain literal defaults
+* declared in the schema/IR — anything not expressible as JSON (functions,
+* `Date`, `RegExp`, class instances, `undefined`) is rejected at the type level.
+*/
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+	[key: string]: JsonValue;
+};

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

@@ -0,0 +1 @@
+{"mappings":";;;;;AAqBA,YAAY,+CAKR,cACA;gBAAiB","names":[],"sources":["../../../src/types/JsonValue.ts"],"version":3,"file":"JsonValue.d.ts"}

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

@@ -1,3 +1,4 @@
+import type { JsonValue } from "./JsonValue.js";
 /** Type descriptor for a field, enabling recursive lens application. */
 export type FieldTypeDescriptor = {
 	kind: "primitive";
@@ -16,19 +17,19 @@ export type 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.
+	* Source field names. When empty, the field is additive — only `default` applies and no
+	* forward function is invoked.
 	*/
 	derivedFrom: string[];
-	forward: (oldFields: Record<string, unknown>) => unknown;
-	default?: unknown;
+	/** Literal JSON only — validated at schema build time. Used when no source data exists. */
+	default?: JsonValue;
 }
 export interface FieldDef {
 	type: FieldTypeDescriptor;
 	default?: unknown;
 }
 export interface UpgradeStepDef {
-	name: string;
+	/** Schema version this step upgrades to. Unique within a model's chain. */
 	addedInVersion: number;
 	fields: Record<string, FieldLensDef>;
 	removedFields?: string[];
@@ -54,3 +55,17 @@ export interface UnionUpgradeRegistry<ModelName extends string = string> {
 }
 export type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
 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`.
+*
+* The generated `DocumentUpgradeFns` interface is a precisely-typed refinement
+* of this shape; both `BaseYjsDocumentService` and `applyReadLens` read from
+* it via this loose type.
+*
+* Paired with `UpgradeRegistry`: the registry is the structural spec (WHEN to
+* upgrade and from which fields), `UpgradeFns` provides the implementations.
+*/
+export type UpgradeFns = Record<string, Record<string, Record<string, (oldFields: any) => any>>>;

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;;;;;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"}
+{"mappings":"AAgBA,cAAc,iBAAiB;;AAG/B,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;;CAEA,UAAU;;AAGZ,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.document-schema.model-types",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@palantir/pack.core": "~0.2.2"
+    "@palantir/pack.core": "~0.3.0"
   },
   "peerDependencies": {
     "zod": "^4.1.7"

package/src/index.ts

@@ -50,6 +50,7 @@ export type {
   DocumentSchemaMetadata,
   DocumentState,
 } from "./types/DocumentSchema.js";
+export type { JsonValue } from "./types/JsonValue.js";
 export { MediaRefBrand } from "./types/MediaRef.js";
 export type { MediaId, MediaRef } from "./types/MediaRef.js";
 export { getMetadata, hasMetadata, Metadata } from "./types/Metadata.js";
@@ -84,6 +85,7 @@ export type {
   FieldLensDef,
   FieldTypeDescriptor,
   UnionUpgradeRegistry,
+  UpgradeFns,
   UpgradeRegistry,
   UpgradeRegistryEntry,
   UpgradeRegistryMap,

package/src/types/DocumentSchema.ts

@@ -16,7 +16,7 @@
 
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
-import type { UpgradeRegistryMap } from "./UpgradeLens.js";
+import type { UpgradeFns, UpgradeRegistryMap } from "./UpgradeLens.js";
 
 /**
  * The base type for an application sdk's generated document schema.
@@ -36,4 +36,11 @@ export interface DocumentSchemaMetadata {
   readonly version: number;
   readonly minSupportedVersion?: number;
   readonly upgrades?: UpgradeRegistryMap;
+  /**
+   * Typed forward functions, supplied by the app at boot via the generated
+   * `DocumentModel(...)` factory. Populated when the schema has any derived
+   * fields; absent for schemas that don't need any (single-version or purely
+   * additive across versions). Paired with `upgrades` (the structural spec).
+   */
+  readonly upgradeFns?: UpgradeFns;
 }

package/src/types/JsonValue.ts

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+
+/**
+ * Any value losslessly representable as JSON. Used to constrain literal defaults
+ * declared in the schema/IR — anything not expressible as JSON (functions,
+ * `Date`, `RegExp`, class instances, `undefined`) is rejected at the type level.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };

package/src/types/UpgradeLens.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+import type { JsonValue } from "./JsonValue.js";
+
 /** Type descriptor for a field, enabling recursive lens application. */
 export type FieldTypeDescriptor =
   | { kind: "primitive" }
@@ -24,12 +26,12 @@ export type 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.
+   * Source field names. When empty, the field is additive — only `default` applies and no
+   * forward function is invoked.
    */
   derivedFrom: string[];
-  forward: (oldFields: Record<string, unknown>) => unknown;
-  default?: unknown;
+  /** Literal JSON only — validated at schema build time. Used when no source data exists. */
+  default?: JsonValue;
 }
 
 export interface FieldDef {
@@ -38,7 +40,7 @@ export interface FieldDef {
 }
 
 export interface UpgradeStepDef {
-  name: string;
+  /** Schema version this step upgrades to. Unique within a model's chain. */
   addedInVersion: number;
   fields: Record<string, FieldLensDef>;
   removedFields?: string[];
@@ -68,3 +70,21 @@ export interface UnionUpgradeRegistry<ModelName extends string = string> {
 export type UpgradeRegistryEntry = UpgradeRegistry | UnionUpgradeRegistry;
 
 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`.
+ *
+ * The generated `DocumentUpgradeFns` interface is a precisely-typed refinement
+ * of this shape; both `BaseYjsDocumentService` and `applyReadLens` read from
+ * it via this loose type.
+ *
+ * Paired with `UpgradeRegistry`: the registry is the structural spec (WHEN to
+ * upgrade and from which fields), `UpgradeFns` provides the implementations.
+ */
+export type UpgradeFns = Record<
+  string,
+  Record<string, Record<string, (oldFields: any) => any>>
+>;