Show opaque marker when deserializing custom classes and instances in o11y

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});

.changeset/forty-tables-lick.md

@@ -0,0 +1,6 @@
+---
+"@workflow/web-shared": patch
+"@workflow/core": patch
+---
+
+Show custom class serialization UI and class names in o11y

packages/core/src/observability.test.ts

@@ -0,0 +1,369 @@
+import { inspect } from 'node:util';
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
+import { describe, expect, it } from 'vitest';
+import { registerSerializationClass } from './class-serialization.js';
+import {
+ CLASS_INSTANCE_REF_TYPE,
+ ClassInstanceRef,
+ extractStreamIds,
+ hydrateResourceIO,
+ isClassInstanceRef,
+ isStreamId,
+ isStreamRef,
+ STREAM_REF_TYPE,
+ truncateId,
+} from './observability.js';
+import { dehydrateStepReturnValue } from './serialization.js';
+
+describe('ClassInstanceRef', () => {
+ describe('constructor and properties', () => {
+ it('should create instance with correct properties', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.className).toBe('Point');
+ expect(ref.classId).toBe('class//file.ts//Point');
+ expect(ref.data).toEqual({ x: 1, y: 2 });
+ expect(ref.__type).toBe(CLASS_INSTANCE_REF_TYPE);
+ });
+
+ it('should handle various data types', () => {
+ // Object data
+ const objRef = new ClassInstanceRef('Config', 'class//Config', {
+ key: 'value',
+ });
+ expect(objRef.data).toEqual({ key: 'value' });
+
+ // String data
+ const strRef = new ClassInstanceRef('Token', 'class//Token', 'abc123');
+ expect(strRef.data).toBe('abc123');
+
+ // Number data
+ const numRef = new ClassInstanceRef('Counter', 'class//Counter', 42);
+ expect(numRef.data).toBe(42);
+
+ // Null data
+ const nullRef = new ClassInstanceRef('Empty', 'class//Empty', null);
+ expect(nullRef.data).toBeNull();
+
+ // Array data
+ const arrRef = new ClassInstanceRef('List', 'class//List', [1, 2, 3]);
+ expect(arrRef.data).toEqual([1, 2, 3]);
+ });
+ });
+
+ describe('toJSON()', () => {
+ it('should return plain object representation', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ expect(ref.toJSON()).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+
+ it('should be used by JSON.stringify', () => {
+ const ref = new ClassInstanceRef('Point', 'class//file.ts//Point', {
+ x: 1,
+ y: 2,
+ });
+
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ expect(parsed).toEqual({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//file.ts//Point',
+ data: { x: 1, y: 2 },
+ });
+ });
+ });
+
+ describe('[inspect.custom]', () => {
+ it('should render as ClassName@filename { data }', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/user-signup.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Point@user-signup.ts { x: 1, y: 2 }');
+ });
+
+ it('should handle nested file paths', () => {
+ const ref = new ClassInstanceRef(
+ 'Config',
+ 'class//lib/models/config.ts//Config',
+ { nested: { a: 1, b: 2 } }
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Config@config.ts { nested: { a: 1, b: 2 } }');
+ });
+
+ it('should handle string data', () => {
+ const ref = new ClassInstanceRef(
+ 'Token',
+ 'class//auth/token.ts//Token',
+ 'secret'
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe("Token@token.ts 'secret'");
+ });
+
+ it('should handle null data', () => {
+ const ref = new ClassInstanceRef(
+ 'Empty',
+ 'class//utils/empty.ts//Empty',
+ null
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('Empty@empty.ts null');
+ });
+
+ it('should handle array data', () => {
+ const ref = new ClassInstanceRef(
+ 'List',
+ 'class//collections/list.ts//List',
+ [1, 2, 3]
+ );
+
+ const output = inspect(ref, { colors: false });
+ expect(output).toBe('List@list.ts [ 1, 2, 3 ]');
+ });
+
+ it('should handle simple classId format gracefully', () => {
+ // Fallback for non-standard classId format
+ const ref = new ClassInstanceRef('Point', 'test//TestPoint', {
+ x: 1,
+ y: 2,
+ });
+
+ const output = inspect(ref, { colors: false });
+ // Falls back to extracting just the last segment as filename
+ expect(output).toBe('Point@TestPoint { x: 1, y: 2 }');
+ });
+
+ it('should style @filename gray when colors are enabled', () => {
+ const ref = new ClassInstanceRef(
+ 'Point',
+ 'class//workflows/point.ts//Point',
+ { x: 1, y: 2 }
+ );
+
+ const output = inspect(ref, { colors: true });
+ // When colors are enabled, the @filename should have ANSI escape codes
+ expect(output).toContain('Point');
+ // Check for ANSI escape codes (gray/dim styling for @filename)
+ expect(output).toMatch(/\x1b\[90m@point\.ts\x1b\[39m/);
+ // Data is also present (may have color codes for numbers)
+ expect(output).toContain('x:');
+ expect(output).toContain('y:');
+ });
+ });
+});
+
+describe('isClassInstanceRef', () => {
+ it('should return true for ClassInstanceRef instances', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ expect(isClassInstanceRef(ref)).toBe(true);
+ });
+
+ it('should return true for plain objects with correct structure', () => {
+ const plainObj = {
+ __type: CLASS_INSTANCE_REF_TYPE,
+ className: 'Point',
+ classId: 'class//Point',
+ data: { x: 1, y: 2 },
+ };
+ expect(isClassInstanceRef(plainObj)).toBe(true);
+ });
+
+ it('should return true for JSON-parsed ClassInstanceRef', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const parsed = JSON.parse(JSON.stringify(ref));
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isClassInstanceRef(null)).toBe(false);
+ });
+
+ it('should return false for undefined', () => {
+ expect(isClassInstanceRef(undefined)).toBe(false);
+ });
+
+ it('should return false for plain objects without __type', () => {
+ expect(isClassInstanceRef({ className: 'Point', data: {} })).toBe(false);
+ });
+
+ it('should return false for objects with wrong __type', () => {
+ expect(
+ isClassInstanceRef({
+ __type: 'wrong_type',
+ className: 'Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+
+ it('should return false for objects without className', () => {
+ expect(
+ isClassInstanceRef({
+ __type: CLASS_INSTANCE_REF_TYPE,
+ classId: 'class//Point',
+ data: {},
+ })
+ ).toBe(false);
+ });
+});
+
+describe('isStreamRef', () => {
+ it('should return true for valid StreamRef', () => {
+ const streamRef = {
+ __type: STREAM_REF_TYPE,
+ streamId: 'strm_123',
+ };
+ expect(isStreamRef(streamRef)).toBe(true);
+ });
+
+ it('should return false for null', () => {
+ expect(isStreamRef(null)).toBe(false);
+ });
+
+ it('should return false for wrong __type', () => {
+ expect(isStreamRef({ __type: 'wrong', streamId: 'strm_123' })).toBe(false);
+ });
+});
+
+describe('isStreamId', () => {
+ it('should return true for valid stream ID', () => {
+ expect(isStreamId('strm_abc123')).toBe(true);
+ });
+
+ it('should return false for non-stream strings', () => {
+ expect(isStreamId('not_a_stream')).toBe(false);
+ });
+
+ it('should return false for non-strings', () => {
+ expect(isStreamId(123)).toBe(false);
+ expect(isStreamId(null)).toBe(false);
+ expect(isStreamId({})).toBe(false);
+ });
+});
+
+describe('extractStreamIds', () => {
+ it('should extract stream IDs from flat objects', () => {
+ const obj = { stream: 'strm_123', other: 'not_stream' };
+ expect(extractStreamIds(obj)).toEqual(['strm_123']);
+ });
+
+ it('should extract stream IDs from nested objects', () => {
+ const obj = {
+ level1: {
+ level2: {
+ stream: 'strm_abc',
+ },
+ },
+ };
+ expect(extractStreamIds(obj)).toEqual(['strm_abc']);
+ });
+
+ it('should extract stream IDs from arrays', () => {
+ const arr = ['strm_1', 'strm_2', 'not_stream'];
+ expect(extractStreamIds(arr)).toEqual(['strm_1', 'strm_2']);
+ });
+
+ it('should deduplicate stream IDs', () => {
+ const obj = { a: 'strm_same', b: 'strm_same' };
+ expect(extractStreamIds(obj)).toEqual(['strm_same']);
+ });
+
+ it('should return empty array for no streams', () => {
+ expect(extractStreamIds({ foo: 'bar' })).toEqual([]);
+ });
+});
+
+describe('truncateId', () => {
+ it('should not truncate short IDs', () => {
+ expect(truncateId('short', 12)).toBe('short');
+ });
+
+ it('should truncate long IDs', () => {
+ expect(truncateId('verylongidentifier', 12)).toBe('verylongiden...');
+ });
+
+ it('should use default max length of 12', () => {
+ expect(truncateId('123456789012')).toBe('123456789012');
+ expect(truncateId('1234567890123')).toBe('123456789012...');
+ });
+});
+
+describe('hydrateResourceIO with custom class instances', () => {
+ // Create a test class with serialization symbols
+ class TestPoint {
+ constructor(
+ public x: number,
+ public y: number
+ ) {}
+
+ static [WORKFLOW_SERIALIZE](instance: TestPoint) {
+ return { x: instance.x, y: instance.y };
+ }
+
+ static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+ return new TestPoint(data.x, data.y);
+ }
+ }
+
+ // Register the class for serialization (so dehydrate works)
+ // but note: in o11y context, classes are NOT registered, which is the point of this test
+ (TestPoint as any).classId = 'test//TestPoint';
+ registerSerializationClass('test//TestPoint', TestPoint);
+
+ it('should convert Instance type to ClassInstanceRef in step output', () => {
+ // Simulate serialized step data with a custom class instance
+ const point = new TestPoint(3, 4);
+ const serialized = dehydrateStepReturnValue(point, [], 'wrun_test');
+
+ // Create a step resource with serialized output
+ const step = {
+ stepId: 'step_123',
+ runId: 'wrun_test',
+ output: serialized,
+ };
+
+ // Hydrate the step - this should convert Instance to ClassInstanceRef
+ // because the class is not registered in the o11y context (streamPrintRevivers)
+ const hydrated = hydrateResourceIO(step);
+
+ // The output should be a ClassInstanceRef
+ expect(isClassInstanceRef(hydrated.output)).toBe(true);
+ expect(hydrated.output.className).toBe('TestPoint');
+ expect(hydrated.output.classId).toBe('test//TestPoint');
+ expect(hydrated.output.data).toEqual({ x: 3, y: 4 });
+ });
+
+ it('should preserve ClassInstanceRef through JSON roundtrip', () => {
+ const ref = new ClassInstanceRef('Point', 'class//Point', { x: 1, y: 2 });
+ const json = JSON.stringify(ref);
+ const parsed = JSON.parse(json);
+
+ // After parsing, it's a plain object but still recognized
+ expect(isClassInstanceRef(parsed)).toBe(true);
+ expect(parsed.className).toBe('Point');
+ expect(parsed.classId).toBe('class//Point');
+ expect(parsed.data).toEqual({ x: 1, y: 2 });
+ });
+});