rivetkit 2.0.24-rc.1 → 2.0.25-rc.1

package/src/remote-manager-driver/mod.ts

@@ -4,6 +4,7 @@ import invariant from "invariant";
 import { deserializeActorKey, serializeActorKey } from "@/actor/keys";
 import { generateRandomString } from "@/actor/utils";
 import type { ClientConfig } from "@/client/client";
+import type { MetadataResponse } from "@/common/router";
 import { noopNext, stringifyError } from "@/common/utils";
 import type {
 	ActorOutput,
@@ -11,6 +12,7 @@ import type {
 	GetForIdInput,
 	GetOrCreateWithKeyInput,
 	GetWithKeyInput,
+	ListActorsInput,
 	ManagerDisplayInformation,
 	ManagerDriver,
 } from "@/driver-helpers/mod";
@@ -29,9 +31,11 @@ import {
 	getActorByKey,
 	getMetadata,
 	getOrCreateActor,
+	listActorsByName,
 } from "./api-endpoints";
 import { EngineApiError, getEndpoint } from "./api-utils";
 import { logger } from "./log";
+import { lookupMetadataCached } from "./metadata";
 import { createWebSocketProxy } from "./ws-proxy";
 
 // TODO:
@@ -48,9 +52,6 @@ import { createWebSocketProxy } from "./ws-proxy";
 // 	};
 // })();
 
-// Global cache to store metadata check promises for each endpoint
-const metadataCheckCache = new Map<string, Promise<void>>();
-
 export class RemoteManagerDriver implements ManagerDriver {
 	#config: ClientConfig;
 	#metadataPromise: Promise<void> | undefined;
@@ -63,64 +64,38 @@ export class RemoteManagerDriver implements ManagerDriver {
 			logger().info(
 				"detected next.js build phase, disabling health check",
 			);
-			runConfig.disableHealthCheck = true;
+			runConfig.disableMetadataLookup = true;
 		}
 
-		this.#config = runConfig;
+		// Clone config so we can mutate the endpoint in #metadataPromise
+		// NOTE: This is a shallow clone, so mutating nested properties will not do anything
+		this.#config = { ...runConfig };
 
 		// Perform metadata check if enabled
-		if (!runConfig.disableHealthCheck) {
-			this.#metadataPromise = this.#performMetadataCheck(runConfig);
-			this.#metadataPromise.catch((error) => {
-				logger().error({
-					msg: "metadata check failed",
-					error:
-						error instanceof Error ? error.message : String(error),
-				});
-			});
-		}
-	}
-
-	async #performMetadataCheck(config: ClientConfig): Promise<void> {
-		const endpoint = getEndpoint(config);
+		if (!runConfig.disableMetadataLookup) {
+			// This should never error, since it uses pRetry. If it does for
+			// any reason, we'll surface the error anywhere #metadataPromise is
+			// awaited.
+			this.#metadataPromise = lookupMetadataCached(this.#config).then(
+				(metadataData) => {
+					// Override endpoint for all future requests
+					if (metadataData.clientEndpoint) {
+						this.#config.endpoint = metadataData.clientEndpoint;
+						logger().info({
+							msg: "overriding cached client endpoint",
+							endpoint: metadataData.clientEndpoint,
+						});
+					}
 
-		// Check if metadata check is already in progress or completed for this endpoint
-		const existingPromise = metadataCheckCache.get(endpoint);
-		if (existingPromise) {
-			return existingPromise;
-		}
-
-		// Create and store the promise immediately to prevent racing requests
-		const metadataCheckPromise = (async () => {
-			try {
-				const metadataData = await getMetadata(config);
-
-				if (metadataData.clientEndpoint) {
 					logger().info({
-						msg: "received new client endpoint from metadata",
-						endpoint: metadataData.clientEndpoint,
+						msg: "connected to rivetkit manager",
+						runtime: metadataData.runtime,
+						version: metadataData.version,
+						runner: metadataData.runner,
 					});
-					this.#config.endpoint = metadataData.clientEndpoint;
-				}
-
-				// Log successful metadata check with runtime and version info
-				logger().info({
-					msg: "connected to rivetkit manager",
-					runtime: metadataData.runtime,
-					version: metadataData.version,
-					runner: metadataData.runner,
-				});
-			} catch (error) {
-				logger().error({
-					msg: "health check failed, validate the Rivet endpoint is configured correctly",
-					endpoint,
-					error: stringifyError(error),
-				});
-			}
-		})();
-
-		metadataCheckCache.set(endpoint, metadataCheckPromise);
-		return metadataCheckPromise;
+				},
+			);
+		}
 	}
 
 	async getForId({
@@ -282,6 +257,24 @@ export class RemoteManagerDriver implements ManagerDriver {
 		};
 	}
 
+	async listActors({ c, name }: ListActorsInput): Promise<ActorOutput[]> {
+		// Wait for metadata check to complete if in progress
+		if (this.#metadataPromise) {
+			await this.#metadataPromise;
+		}
+
+		logger().debug({ msg: "listing actors via engine api", name });
+
+		const response = await listActorsByName(this.#config, name);
+
+		return response.actors.map((actor) => ({
+			actorId: actor.actor_id,
+			name: actor.name,
+			key: deserializeActorKey(actor.key),
+			createTs: actor.create_ts,
+		}));
+	}
+
 	async destroyActor(actorId: string): Promise<void> {
 		// Wait for metadata check to complete if in progress
 		if (this.#metadataPromise) {
@@ -316,8 +309,6 @@ export class RemoteManagerDriver implements ManagerDriver {
 		actorId: string,
 		encoding: Encoding,
 		params: unknown,
-		connId?: string,
-		connToken?: string,
 	): Promise<UniversalWebSocket> {
 		// Wait for metadata check to complete if in progress
 		if (this.#metadataPromise) {
@@ -330,8 +321,6 @@ export class RemoteManagerDriver implements ManagerDriver {
 			actorId,
 			encoding,
 			params,
-			connId,
-			connToken,
 		);
 	}
 
@@ -358,8 +347,6 @@ export class RemoteManagerDriver implements ManagerDriver {
 		actorId: string,
 		encoding: Encoding,
 		params: unknown,
-		connId?: string,
-		connToken?: string,
 	): Promise<Response> {
 		// Wait for metadata check to complete if in progress
 		if (this.#metadataPromise) {
@@ -385,8 +372,6 @@ export class RemoteManagerDriver implements ManagerDriver {
 			this.#config,
 			encoding,
 			params,
-			connId,
-			connToken,
 		);
 		const args = await createWebSocketProxy(c, wsGuardUrl, protocols);
 

package/src/remote-manager-driver/ws-proxy.ts

@@ -1,8 +1,8 @@
 import type { Context as HonoContext } from "hono";
 import type { WSContext } from "hono/ws";
+import type { UpgradeWebSocketArgs } from "@/actor/router-websocket-endpoints";
 import { stringifyError } from "@/common/utils";
 import { importWebSocket } from "@/common/websocket";
-import type { UpgradeWebSocketArgs } from "@/mod";
 import { logger } from "./log";
 
 /**

package/src/schemas/actor-persist/mod.ts

@@ -1 +1 @@
-export * from "../../../dist/schemas/actor-persist/v2";
+export * from "../../../dist/schemas/actor-persist/v3";

package/src/schemas/actor-persist/versioned.ts

@@ -3,39 +3,64 @@ import {
 	type MigrationFn,
 } from "@/common/versioned-data";
 import type * as v1 from "../../../dist/schemas/actor-persist/v1";
-import * as v2 from "../../../dist/schemas/actor-persist/v2";
+import type * as v2 from "../../../dist/schemas/actor-persist/v2";
+import * as v3 from "../../../dist/schemas/actor-persist/v3";
 
-export const CURRENT_VERSION = 2;
+export const CURRENT_VERSION = 3;
 
-export type CurrentPersistedActor = v2.PersistedActor;
-export type CurrentPersistedConnection = v2.PersistedConnection;
-export type CurrentPersistedSubscription = v2.PersistedSubscription;
-export type CurrentGenericPersistedScheduleEvent =
-	v2.GenericPersistedScheduleEvent;
-export type CurrentPersistedScheduleEventKind = v2.PersistedScheduleEventKind;
-export type CurrentPersistedScheduleEvent = v2.PersistedScheduleEvent;
-export type CurrentPersistedHibernatableWebSocket =
-	v2.PersistedHibernatableWebSocket;
+const migrations = new Map<number, MigrationFn<any, any>>([
+	[
+		1,
+		(v1Data: v1.PersistedActor): v2.PersistedActor => ({
+			...v1Data,
+			connections: v1Data.connections.map((conn) => ({
+				...conn,
+				hibernatableRequestId: null,
+			})),
+			hibernatableWebSockets: [],
+		}),
+	],
+	[
+		2,
+		(v2Data: v2.PersistedActor): v3.Actor => {
+			// Transform scheduled events from nested structure to flat structure
+			const scheduledEvents: v3.ScheduleEvent[] =
+				v2Data.scheduledEvents.map((event) => {
+					// Extract action and args from the kind wrapper
+					if (event.kind.tag === "GenericPersistedScheduleEvent") {
+						return {
+							eventId: event.eventId,
+							timestamp: event.timestamp,
+							action: event.kind.val.action,
+							args: event.kind.val.args,
+						};
+					}
+					// Fallback for unknown kinds
+					throw new Error(
+						`Unknown schedule event kind: ${event.kind.tag}`,
+					);
+				});
 
-const migrations = new Map<number, MigrationFn<any, any>>();
+			return {
+				input: v2Data.input,
+				hasInitialized: v2Data.hasInitialized,
+				state: v2Data.state,
+				scheduledEvents,
+			};
+		},
+	],
+]);
 
-// Migration from v1 to v2: Add hibernatableWebSocket field
-migrations.set(
-	1,
-	(v1Data: v1.PersistedActor): v2.PersistedActor => ({
-		...v1Data,
-		connections: v1Data.connections.map((conn) => ({
-			...conn,
-			hibernatableRequestId: null,
-		})),
-		hibernatableWebSocket: [],
-	}),
-);
+export const ACTOR_VERSIONED = createVersionedDataHandler<v3.Actor>({
+	currentVersion: CURRENT_VERSION,
+	migrations,
+	serializeVersion: (data) => v3.encodeActor(data),
+	deserializeVersion: (bytes) => v3.decodeActor(bytes),
+});
 
-export const PERSISTED_ACTOR_VERSIONED =
-	createVersionedDataHandler<CurrentPersistedActor>({
-		currentVersion: CURRENT_VERSION,
-		migrations,
-		serializeVersion: (data) => v2.encodePersistedActor(data),
-		deserializeVersion: (bytes) => v2.decodePersistedActor(bytes),
-	});
+export const CONN_VERSIONED = createVersionedDataHandler<v3.Conn>({
+	currentVersion: CURRENT_VERSION,
+	migrations: new Map(),
+	serializeVersion: (data) => v3.encodeConn(data),
+	deserializeVersion: (bytes) => v3.decodeConn(bytes),
+});

package/src/schemas/client-protocol/mod.ts

@@ -1 +1 @@
-export * from "../../../dist/schemas/client-protocol/v1";
+export * from "../../../dist/schemas/client-protocol/v2";

package/src/schemas/client-protocol/versioned.ts

@@ -2,52 +2,72 @@ import {
 	createVersionedDataHandler,
 	type MigrationFn,
 } from "@/common/versioned-data";
-import * as v1 from "../../../dist/schemas/client-protocol/v1";
+import type * as v1 from "../../../dist/schemas/client-protocol/v1";
+import * as v2 from "../../../dist/schemas/client-protocol/v2";
 
-export const CURRENT_VERSION = 1;
+export const CURRENT_VERSION = 2;
 
 const migrations = new Map<number, MigrationFn<any, any>>();
 
-export const TO_SERVER_VERSIONED = createVersionedDataHandler<v1.ToServer>({
+// Migration from v1 to v2: Remove connectionToken from Init message
+migrations.set(1, (v1Data: v1.ToClient): v2.ToClient => {
+	// Handle Init message specifically to remove connectionToken
+	if (v1Data.body.tag === "Init") {
+		const { actorId, connectionId } = v1Data.body.val as v1.Init;
+		return {
+			body: {
+				tag: "Init",
+				val: {
+					actorId,
+					connectionId,
+				},
+			},
+		};
+	}
+	// All other messages are unchanged
+	return v1Data as unknown as v2.ToClient;
+});
+
+export const TO_SERVER_VERSIONED = createVersionedDataHandler<v2.ToServer>({
 	currentVersion: CURRENT_VERSION,
 	migrations,
-	serializeVersion: (data) => v1.encodeToServer(data),
-	deserializeVersion: (bytes) => v1.decodeToServer(bytes),
+	serializeVersion: (data) => v2.encodeToServer(data),
+	deserializeVersion: (bytes) => v2.decodeToServer(bytes),
 });
 
-export const TO_CLIENT_VERSIONED = createVersionedDataHandler<v1.ToClient>({
+export const TO_CLIENT_VERSIONED = createVersionedDataHandler<v2.ToClient>({
 	currentVersion: CURRENT_VERSION,
 	migrations,
-	serializeVersion: (data) => v1.encodeToClient(data),
-	deserializeVersion: (bytes) => v1.decodeToClient(bytes),
+	serializeVersion: (data) => v2.encodeToClient(data),
+	deserializeVersion: (bytes) => v2.decodeToClient(bytes),
 });
 
 export const HTTP_ACTION_REQUEST_VERSIONED =
-	createVersionedDataHandler<v1.HttpActionRequest>({
+	createVersionedDataHandler<v2.HttpActionRequest>({
 		currentVersion: CURRENT_VERSION,
 		migrations,
-		serializeVersion: (data) => v1.encodeHttpActionRequest(data),
-		deserializeVersion: (bytes) => v1.decodeHttpActionRequest(bytes),
+		serializeVersion: (data) => v2.encodeHttpActionRequest(data),
+		deserializeVersion: (bytes) => v2.decodeHttpActionRequest(bytes),
 	});
 
 export const HTTP_ACTION_RESPONSE_VERSIONED =
-	createVersionedDataHandler<v1.HttpActionResponse>({
+	createVersionedDataHandler<v2.HttpActionResponse>({
 		currentVersion: CURRENT_VERSION,
 		migrations,
-		serializeVersion: (data) => v1.encodeHttpActionResponse(data),
-		deserializeVersion: (bytes) => v1.decodeHttpActionResponse(bytes),
+		serializeVersion: (data) => v2.encodeHttpActionResponse(data),
+		deserializeVersion: (bytes) => v2.decodeHttpActionResponse(bytes),
 	});
 
 export const HTTP_RESPONSE_ERROR_VERSIONED =
-	createVersionedDataHandler<v1.HttpResponseError>({
+	createVersionedDataHandler<v2.HttpResponseError>({
 		currentVersion: CURRENT_VERSION,
 		migrations,
-		serializeVersion: (data) => v1.encodeHttpResponseError(data),
-		deserializeVersion: (bytes) => v1.decodeHttpResponseError(bytes),
+		serializeVersion: (data) => v2.encodeHttpResponseError(data),
+		deserializeVersion: (bytes) => v2.decodeHttpResponseError(bytes),
 	});
 
 export const HTTP_RESOLVE_REQUEST_VERSIONED =
-	createVersionedDataHandler<v1.HttpResolveRequest>({
+	createVersionedDataHandler<v2.HttpResolveRequest>({
 		currentVersion: CURRENT_VERSION,
 		migrations,
 		serializeVersion: (_) => new Uint8Array(),
@@ -55,9 +75,9 @@ export const HTTP_RESOLVE_REQUEST_VERSIONED =
 	});
 
 export const HTTP_RESOLVE_RESPONSE_VERSIONED =
-	createVersionedDataHandler<v1.HttpResolveResponse>({
+	createVersionedDataHandler<v2.HttpResolveResponse>({
 		currentVersion: CURRENT_VERSION,
 		migrations,
-		serializeVersion: (data) => v1.encodeHttpResolveResponse(data),
-		deserializeVersion: (bytes) => v1.decodeHttpResolveResponse(bytes),
+		serializeVersion: (data) => v2.encodeHttpResolveResponse(data),
+		deserializeVersion: (bytes) => v2.decodeHttpResolveResponse(bytes),
 	});

package/src/schemas/client-protocol-zod/mod.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+// Helper schemas
+const UintSchema = z.bigint();
+const OptionalUintSchema = UintSchema.nullable();
+
+// MARK: Message To Client
+export const InitSchema = z.object({
+	actorId: z.string(),
+	connectionId: z.string(),
+});
+export type Init = z.infer<typeof InitSchema>;
+
+export const ErrorSchema = z.object({
+	group: z.string(),
+	code: z.string(),
+	message: z.string(),
+	metadata: z.unknown().optional(),
+	actionId: OptionalUintSchema,
+});
+export type Error = z.infer<typeof ErrorSchema>;
+
+export const ActionResponseSchema = z.object({
+	id: UintSchema,
+	output: z.unknown(),
+});
+export type ActionResponse = z.infer<typeof ActionResponseSchema>;
+
+export const EventSchema = z.object({
+	name: z.string(),
+	args: z.unknown(),
+});
+export type Event = z.infer<typeof EventSchema>;
+
+export const ToClientBodySchema = z.discriminatedUnion("tag", [
+	z.object({ tag: z.literal("Init"), val: InitSchema }),
+	z.object({ tag: z.literal("Error"), val: ErrorSchema }),
+	z.object({ tag: z.literal("ActionResponse"), val: ActionResponseSchema }),
+	z.object({ tag: z.literal("Event"), val: EventSchema }),
+]);
+export type ToClientBody = z.infer<typeof ToClientBodySchema>;
+
+export const ToClientSchema = z.object({
+	body: ToClientBodySchema,
+});
+export type ToClient = z.infer<typeof ToClientSchema>;
+
+// MARK: Message To Server
+export const ActionRequestSchema = z.object({
+	id: UintSchema,
+	name: z.string(),
+	args: z.unknown(),
+});
+export type ActionRequest = z.infer<typeof ActionRequestSchema>;
+
+export const SubscriptionRequestSchema = z.object({
+	eventName: z.string(),
+	subscribe: z.boolean(),
+});
+export type SubscriptionRequest = z.infer<typeof SubscriptionRequestSchema>;
+
+export const ToServerBodySchema = z.discriminatedUnion("tag", [
+	z.object({ tag: z.literal("ActionRequest"), val: ActionRequestSchema }),
+	z.object({
+		tag: z.literal("SubscriptionRequest"),
+		val: SubscriptionRequestSchema,
+	}),
+]);
+export type ToServerBody = z.infer<typeof ToServerBodySchema>;
+
+export const ToServerSchema = z.object({
+	body: ToServerBodySchema,
+});
+export type ToServer = z.infer<typeof ToServerSchema>;
+
+// MARK: HTTP Action
+export const HttpActionRequestSchema = z.object({
+	args: z.unknown(),
+});
+export type HttpActionRequest = z.infer<typeof HttpActionRequestSchema>;
+
+export const HttpActionResponseSchema = z.object({
+	output: z.unknown(),
+});
+export type HttpActionResponse = z.infer<typeof HttpActionResponseSchema>;
+
+// MARK: HTTP Error
+export const HttpResponseErrorSchema = z.object({
+	group: z.string(),
+	code: z.string(),
+	message: z.string(),
+	metadata: z.unknown().optional(),
+});
+export type HttpResponseError = z.infer<typeof HttpResponseErrorSchema>;
+
+// MARK: HTTP Resolve
+export const HttpResolveRequestSchema = z.null();
+export type HttpResolveRequest = z.infer<typeof HttpResolveRequestSchema>;
+
+export const HttpResolveResponseSchema = z.object({
+	actorId: z.string(),
+});
+export type HttpResolveResponse = z.infer<typeof HttpResolveResponseSchema>;

package/src/schemas/file-system-driver/mod.ts

@@ -1 +1 @@
-export * from "../../../dist/schemas/file-system-driver/v1";
+export * from "../../../dist/schemas/file-system-driver/v2";

package/src/schemas/file-system-driver/versioned.ts

@@ -2,27 +2,50 @@ import {
 	createVersionedDataHandler,
 	type MigrationFn,
 } from "@/common/versioned-data";
-import * as v1 from "../../../dist/schemas/file-system-driver/v1";
+import { bufferToArrayBuffer } from "@/utils";
+import type * as v1 from "../../../dist/schemas/file-system-driver/v1";
+import * as v2 from "../../../dist/schemas/file-system-driver/v2";
 
-export const CURRENT_VERSION = 1;
+export const CURRENT_VERSION = 2;
 
-export type CurrentActorState = v1.ActorState;
-export type CurrentActorAlarm = v1.ActorAlarm;
+const migrations = new Map<number, MigrationFn<any, any>>([
+	[
+		2,
+		(v1State: v1.ActorState): v2.ActorState => {
+			// Create a new kvStorage list with the legacy persist data
+			const kvStorage: v2.ActorKvEntry[] = [];
 
-const migrations = new Map<number, MigrationFn<any, any>>();
+			// Store the legacy persist data under key [1]
+			if (v1State.persistedData) {
+				// Key [1] as Uint8Array
+				const key = new Uint8Array([1]);
+				kvStorage.push({
+					key: bufferToArrayBuffer(key),
+					value: v1State.persistedData,
+				});
+			}
 
-export const ACTOR_STATE_VERSIONED =
-	createVersionedDataHandler<CurrentActorState>({
-		currentVersion: CURRENT_VERSION,
-		migrations,
-		serializeVersion: (data) => v1.encodeActorState(data),
-		deserializeVersion: (bytes) => v1.decodeActorState(bytes),
-	});
+			return {
+				actorId: v1State.actorId,
+				name: v1State.name,
+				key: v1State.key,
+				kvStorage,
+				createdAt: v1State.createdAt,
+			};
+		},
+	],
+]);
 
-export const ACTOR_ALARM_VERSIONED =
-	createVersionedDataHandler<CurrentActorAlarm>({
-		currentVersion: CURRENT_VERSION,
-		migrations,
-		serializeVersion: (data) => v1.encodeActorAlarm(data),
-		deserializeVersion: (bytes) => v1.decodeActorAlarm(bytes),
-	});
+export const ACTOR_STATE_VERSIONED = createVersionedDataHandler<v2.ActorState>({
+	currentVersion: CURRENT_VERSION,
+	migrations,
+	serializeVersion: (data) => v2.encodeActorState(data),
+	deserializeVersion: (bytes) => v2.decodeActorState(bytes),
+});
+
+export const ACTOR_ALARM_VERSIONED = createVersionedDataHandler<v2.ActorAlarm>({
+	currentVersion: CURRENT_VERSION,
+	migrations,
+	serializeVersion: (data) => v2.encodeActorAlarm(data),
+	deserializeVersion: (bytes) => v2.decodeActorAlarm(bytes),
+});

package/src/serde.ts

@@ -1,5 +1,6 @@
 import * as cbor from "cbor-x";
 import invariant from "invariant";
+import type { z } from "zod";
 import { assertUnreachable } from "@/common/utils";
 import type { VersionedDataHandler } from "@/common/versioned-data";
 import type { Encoding } from "@/mod";
@@ -52,46 +53,65 @@ export function wsBinaryTypeForEncoding(
 	}
 }
 
-export function serializeWithEncoding<T>(
+export function serializeWithEncoding<TBare, TJson, T = TBare>(
 	encoding: Encoding,
 	value: T,
-	versionedDataHandler: VersionedDataHandler<T> | undefined,
+	versionedDataHandler: VersionedDataHandler<TBare> | undefined,
+	zodSchema: z.ZodType<TJson>,
+	toJson: (value: T) => TJson,
+	toBare: (value: T) => TBare,
 ): Uint8Array | string {
 	if (encoding === "json") {
-		return jsonStringifyCompat(value);
+		const jsonValue = toJson(value);
+		const validated = zodSchema.parse(jsonValue);
+		return jsonStringifyCompat(validated);
 	} else if (encoding === "cbor") {
-		return cbor.encode(value);
+		const jsonValue = toJson(value);
+		const validated = zodSchema.parse(jsonValue);
+		return cbor.encode(validated);
 	} else if (encoding === "bare") {
 		if (!versionedDataHandler) {
 			throw new Error(
 				"VersionedDataHandler is required for 'bare' encoding",
 			);
 		}
-		return versionedDataHandler.serializeWithEmbeddedVersion(value);
+		const bareValue = toBare(value);
+		return versionedDataHandler.serializeWithEmbeddedVersion(bareValue);
 	} else {
 		assertUnreachable(encoding);
 	}
 }
 
-export function deserializeWithEncoding<T>(
+export function deserializeWithEncoding<TBare, TJson, T = TBare>(
 	encoding: Encoding,
 	buffer: Uint8Array | string,
-	versionedDataHandler: VersionedDataHandler<T> | undefined,
+	versionedDataHandler: VersionedDataHandler<TBare> | undefined,
+	zodSchema: z.ZodType<TJson>,
+	fromJson: (value: TJson) => T,
+	fromBare: (value: TBare) => T,
 ): T {
 	if (encoding === "json") {
+		let parsed: unknown;
 		if (typeof buffer === "string") {
-			return jsonParseCompat(buffer);
+			parsed = jsonParseCompat(buffer);
 		} else {
 			const decoder = new TextDecoder("utf-8");
 			const jsonString = decoder.decode(buffer);
-			return jsonParseCompat(jsonString);
+			parsed = jsonParseCompat(jsonString);
 		}
+		const validated = zodSchema.parse(parsed);
+		return fromJson(validated);
 	} else if (encoding === "cbor") {
 		invariant(
 			typeof buffer !== "string",
 			"buffer cannot be string for cbor encoding",
 		);
-		return cbor.decode(buffer);
+		// Decode CBOR to get JavaScript values (similar to JSON.parse)
+		const decoded: unknown = cbor.decode(buffer);
+		// Validate with Zod schema (CBOR produces same structure as JSON)
+		const validated = zodSchema.parse(decoded);
+		// CBOR decoding produces JS objects, use fromJson
+		return fromJson(validated);
 	} else if (encoding === "bare") {
 		invariant(
 			typeof buffer !== "string",
@@ -102,7 +122,9 @@ export function deserializeWithEncoding<T>(
 				"VersionedDataHandler is required for 'bare' encoding",
 			);
 		}
-		return versionedDataHandler.deserializeWithEmbeddedVersion(buffer);
+		const bareValue =
+			versionedDataHandler.deserializeWithEmbeddedVersion(buffer);
+		return fromBare(bareValue);
 	} else {
 		assertUnreachable(encoding);
 	}