Migration Guide

Upgrading from pre-1.0 to Synode v1.0.

SynodeError replaces plain Error throws

All validation and runtime errors now throw SynodeError instead of plain Error. Update catch blocks to use the structured fields:

// Before
try {
  await generate(journey, opts);
} catch (err) {
  console.error(err.message);
}

// After
import { SynodeError } from '@synode/core';

try {
  await generate(journey, opts);
} catch (err) {
  if (err instanceof SynodeError) {
    console.error(err.format()); // structured multi-line output
    console.error(err.code); // e.g. 'HANDLER_ERROR'
    console.error(err.path); // e.g. ['purchase', 'checkout', 'submit']
    console.error(err.suggestion); // e.g. 'Check adapter connection'
  }
}

validateConfig accepts optional allJourneys

validateConfig now takes an optional second argument for cross-journey validation (unknown references, circular dependencies). Existing single-argument calls still work.

// Still works
validateConfig(journey);

// New: cross-journey checks
validateConfig(purchaseJourney, [browseJourney, purchaseJourney]);

Adapters moved to separate packages

Adapters are now in their own @synode/adapter-* packages. Core adapters (Console, InMemory, Callback) remain in @synode/core.

// Core adapters (Console, InMemory, Callback)
import { InMemoryAdapter, ConsoleAdapter, CallbackAdapter } from '@synode/core';

// File, HTTP, Stream, Composite adapters are separate packages
import { FileAdapter } from '@synode/adapter-file';
import { HttpAdapter } from '@synode/adapter-http';
import { StreamAdapter } from '@synode/adapter-stream';
import { CompositeAdapter } from '@synode/adapter-composite';

New exports

The following are now exported from the package root:

• Error system: SynodeError, ErrorCode, SynodeErrorOptions
• Event validation: defineEventSchema, SynodeValidationError, ValidationSummary, ValidationIssue
• Adapters: CallbackAdapter, CompositeAdapter, StreamAdapter, StreamAdapterOptions
• Worker types: WorkerInit, WorkerMessage, SerializedDataset
• CLI config types: SynodeConfig, AdapterConfig (type-only exports)

New RunOptions fields

• eventSchema -- Zod-based event payload validation (see validation docs)
• workerModule -- enables worker thread parallelism (see execution docs)
• workers -- number of worker threads (defaults to CPU core count)

CLI

Synode now ships a CLI binary (synode). If you previously used custom scripts to run generation, consider migrating to the CLI or a synode.config.ts file:

synode generate ./synode.config.ts --users 1000 --lanes 4
synode validate ./synode.config.ts
synode init  # scaffold a starter config