@panagos/jojoscript 0.10.1 → 1.0.0

package/src/pipeline-parser.js

@@ -234,16 +234,38 @@ function parsePipelineStatement(source, statementStart, statementEnd) {
       throw new SyntaxError(`Empty pipeline stage in:\n${statement}`)
     }
 
-    stages.push(parseStage(statement, stageTokens))
+    stages.push(parseStageWithId(statement, stageTokens))
     i = stageEnd - 1
   }
 
+  const ids = stages.map(stage => stage.id).filter(Boolean)
+  const duplicate = ids.find((id, index) => ids.indexOf(id) !== index)
+  if (duplicate) throw new SyntaxError(`Duplicate stage id: @${duplicate}`)
+
   const prefixTokens = tokens.slice(0, inputStartIndex)
   const prefix = prefixTokens.length ? text(statement, prefixTokens).trim() : ''
 
   return { expression, stages, prefix }
 }
 
+export const STAGE_ID = /^[A-Za-z_][\w-]*$/
+
+// A trailing `@id` labels a stage without changing what it computes.
+function parseStageWithId(source, tokens) {
+  let depth = 0
+  for (let i = 0; i < tokens.length; i++) {
+    const value = tokens[i].value
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') depth--
+    else if (value === '@' && depth === 0) {
+      const id = source.slice(tokens[i].end, tokens[tokens.length - 1].end).trim()
+      if (!STAGE_ID.test(id)) throw new SyntaxError(`Invalid stage id: @${id}`)
+      return { ...parseStage(source, tokens.slice(0, i)), id }
+    }
+  }
+  return parseStage(source, tokens)
+}
+
 function metaLiteral(pipelineId, nodeId, type, extra = {}) {
   return JSON.stringify({ id: nodeId, pipelineId, type, ...extra })
 }
@@ -312,7 +334,7 @@ export function emitPipeline(pipeline, options = {}) {
 
   const stagesWithIds = pipeline.stages.map((stage, index) => ({
     ...stage,
-    nodeId: `node-${index + 1}`
+    nodeId: stage.id ?? `node-${index + 1}`
   }))
 
   const stages = fuseRetryStages(stagesWithIds, pipelineId)

package/src/pipeline-plan.js

@@ -0,0 +1,203 @@
+import { compile } from './compiler.js'
+import { findAllPipelines, STAGE_ID } from './pipeline-parser.js'
+import { computePipelineId } from './pipeline-hash.js'
+import { inferPipelineName } from './pipeline-explain.js'
+import { transformNamedPipelines } from './named-pipelines.js'
+
+const PLAN_VERSION = 1
+
+const EXPRESSION_STAGES = new Set([
+  'map', 'filter', 'flatMap', 'tap', 'mapAsync', 'filterAsync', 'find', 'some',
+  'every', 'sortBy', 'distinctBy', 'groupBy', 'partition', 'catch'
+])
+
+const INTEGER_STAGE_FIELDS = { parallel: 'concurrency', batch: 'size' }
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/
+const STAGE_NAME = /^\.?[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/
+const SIMPLE_STRING = /^(["'])([^"'\\]*)\1$/
+
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+
+class PlanValidationError extends Error {
+  constructor(message) {
+    super(`Invalid plan: ${message}`)
+    this.name = 'PlanValidationError'
+  }
+}
+
+/*
+ * The canonical, machine-readable form of every pipeline in `source`.
+ * Arguments stay as source text, so the plan describes computation without
+ * evaluating it and `planToJojo` can reproduce it.
+ */
+export function planPipelines(jojoSource) {
+  const source = transformNamedPipelines(jojoSource)
+  return {
+    version: PLAN_VERSION,
+    pipelines: findAllPipelines(source).map(pipeline => ({
+      pipeline: inferPipelineName(source, pipeline),
+      id: computePipelineId(pipeline),
+      stages: [{ type: 'source', expression: pipeline.expression }, ...pipeline.stages.map(planStage)]
+    }))
+  }
+}
+
+function planStage(stage) {
+  const planned = plannedStage(stage)
+  return stage.id ? { ...planned, id: stage.id } : planned
+}
+
+function plannedStage(stage) {
+  const { name: type, args } = stage
+  const integerField = INTEGER_STAGE_FIELDS[type]
+
+  if (integerField && args.length === 1 && /^[1-9]\d*$/.test(args[0])) {
+    return { type, [integerField]: Number(args[0]) }
+  }
+  if (type === 'checkpoint' && args.length === 1 && SIMPLE_STRING.test(args[0])) {
+    return { type, name: args[0].match(SIMPLE_STRING)[2] }
+  }
+  if (EXPRESSION_STAGES.has(type) && args.length === 1) {
+    return { type, expression: args[0] }
+  }
+  if (stage.propertyCall || args.length) return { type, args }
+  return { type }
+}
+
+export function planToJojo(plan) {
+  validatePlan(plan)
+
+  return plan.pipelines.map((pipeline, index) => {
+    const source = emitPipeline(pipeline)
+    assertCompiles(source, `pipelines[${index}]`)
+    return source
+  }).join('\n\n') + '\n'
+}
+
+function emitPipeline({ pipeline, stages: [source, ...stages] }) {
+  const head = pipeline ? `${pipeline} := ${source.expression}` : source.expression
+  return [head, ...stages.map(stage => `  |> ${emitStage(stage)}`)].join('\n')
+}
+
+function emitStage(stage) {
+  const args = stageArgs(stage)
+  const call = args ? `${stage.type}(${args.join(', ')})` : stage.type
+  return stage.id ? `${call} @${stage.id}` : call
+}
+
+function stageArgs(stage) {
+  if ('expression' in stage) return [stage.expression]
+  if ('name' in stage) return [JSON.stringify(stage.name)]
+  if ('concurrency' in stage) return [String(stage.concurrency)]
+  if ('size' in stage) return [String(stage.size)]
+  return stage.args ?? null
+}
+
+// Building the function only parses the generated code; it is never called.
+function assertCompiles(source, path) {
+  const compiled = compile(source).replace(/^import .*\n/, '')
+  try {
+    new AsyncFunction(compiled)
+  } catch (error) {
+    throw new PlanValidationError(`${path} does not compile to valid JavaScript (${error.message})`)
+  }
+}
+
+function validatePlan(plan) {
+  if (!isObject(plan)) throw new PlanValidationError('plan must be an object')
+  assertKnownFields(plan, ['version', 'pipelines'], '')
+  if (plan.version !== PLAN_VERSION) throw new PlanValidationError(`version must be ${PLAN_VERSION}`)
+  if (!Array.isArray(plan.pipelines)) throw new PlanValidationError('pipelines must be an array')
+
+  const names = new Set()
+  plan.pipelines.forEach((pipeline, index) => {
+    const path = `pipelines[${index}]`
+    if (!isObject(pipeline)) throw new PlanValidationError(`${path} must be an object`)
+    assertKnownFields(pipeline, ['pipeline', 'id', 'stages'], path)
+
+    if (pipeline.pipeline !== null && !IDENTIFIER.test(pipeline.pipeline ?? '')) {
+      throw new PlanValidationError(`${path}.pipeline must be an identifier or null`)
+    }
+    if (names.has(pipeline.pipeline)) {
+      throw new PlanValidationError(`${path}.pipeline "${pipeline.pipeline}" is already declared`)
+    }
+    if (pipeline.pipeline) names.add(pipeline.pipeline)
+
+    if (!Array.isArray(pipeline.stages) || !pipeline.stages.length) {
+      throw new PlanValidationError(`${path}.stages must be a non-empty array`)
+    }
+    const stageIds = new Set()
+    pipeline.stages.forEach((stage, stageIndex) => {
+      const stagePath = `${path}.stages[${stageIndex}]`
+      validateStage(stage, stageIndex, stagePath)
+      if (stage.id === undefined) return
+      if (stageIds.has(stage.id)) throw new PlanValidationError(`${stagePath}.id "${stage.id}" is already used in this pipeline`)
+      stageIds.add(stage.id)
+    })
+  })
+}
+
+function validateStage(stage, index, path) {
+  if (!isObject(stage)) throw new PlanValidationError(`${path} must be an object`)
+
+  if (index === 0) {
+    if (stage.type !== 'source') throw new PlanValidationError(`${path} must be a source stage`)
+    assertKnownFields(stage, ['type', 'expression'], path)
+    assertNonEmptyString(stage.expression, `${path}.expression`)
+    return
+  }
+
+  if (stage.type === 'source') throw new PlanValidationError(`${path} must not be a source stage`)
+  if (typeof stage.type !== 'string' || !STAGE_NAME.test(stage.type)) {
+    throw new PlanValidationError(`${path}.type must be a stage name such as "map" or ".trim"`)
+  }
+
+  const fields = allowedFields(stage.type)
+  assertKnownFields(stage, ['type', 'id', ...fields], path)
+  if (stage.id !== undefined && (typeof stage.id !== 'string' || !STAGE_ID.test(stage.id))) {
+    throw new PlanValidationError(`${path}.id must be a stage id such as "enrich"`)
+  }
+
+  const used = fields.filter(field => field in stage)
+  if (used.length > 1) {
+    throw new PlanValidationError(`${path} must use only one of ${used.map(field => `"${field}"`).join(' or ')}`)
+  }
+
+  const [field] = used
+  if (field === 'concurrency' || field === 'size') {
+    if (!Number.isInteger(stage[field]) || stage[field] <= 0) {
+      throw new PlanValidationError(`${path}.${field} must be a positive integer`)
+    }
+  } else if (field === 'args') {
+    if (!Array.isArray(stage.args) || !stage.args.every(arg => typeof arg === 'string' && arg.trim())) {
+      throw new PlanValidationError(`${path}.args must be an array of non-empty strings`)
+    }
+  } else if (field) {
+    assertNonEmptyString(stage[field], `${path}.${field}`)
+  }
+}
+
+function allowedFields(type) {
+  if (INTEGER_STAGE_FIELDS[type]) return [INTEGER_STAGE_FIELDS[type], 'args']
+  if (type === 'checkpoint') return ['name', 'args']
+  if (EXPRESSION_STAGES.has(type)) return ['expression', 'args']
+  return ['args']
+}
+
+function assertKnownFields(value, fields, path) {
+  const unknown = Object.keys(value).find(key => !fields.includes(key))
+  if (unknown) {
+    throw new PlanValidationError(path ? `${path} has unknown field "${unknown}"` : `unknown field "${unknown}"`)
+  }
+}
+
+function assertNonEmptyString(value, path) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new PlanValidationError(`${path} must be a non-empty string`)
+  }
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/purity.js

@@ -0,0 +1,101 @@
+import { maskNonCode } from './lexer.js'
+import { findEffectDeclarations } from './effect-parser.js'
+
+const PURITY_DECLARATION = /^([ \t]*)(export[ \t]+)?(async[ \t]+)?(pure|effectful)[ \t]+(async[ \t]+)?fn[ \t]+([A-Za-z_$][\w$]*)/gm
+
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+function matchingBrace(code, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < code.length; i++) {
+    if (code[i] === '{' || code[i] === '(') depth++
+    else if ((code[i] === '}' || code[i] === ')') && --depth === 0) return i
+  }
+  return code.length
+}
+
+/*
+ * Body bounds come from the masked source so braces inside strings and
+ * comments never end a body early.
+ */
+function bodyRange(code, nameEnd) {
+  const paramsOpen = code.indexOf('(', nameEnd)
+  const paramsClose = matchingBrace(code, paramsOpen)
+  const rest = code.slice(paramsClose + 1)
+  const head = rest.search(/[{=]/)
+  const start = paramsClose + 1 + head
+
+  if (code[start] === '=') {
+    const lineEnd = code.indexOf('\n', start)
+    return { start, end: lineEnd === -1 ? code.length : lineEnd }
+  }
+  return { start, end: matchingBrace(code, start) + 1 }
+}
+
+export function findPurityDeclarations(source) {
+  const code = maskNonCode(source)
+  const regex = new RegExp(PURITY_DECLARATION.source, PURITY_DECLARATION.flags)
+  const declarations = []
+  let match
+
+  while ((match = regex.exec(code))) {
+    const nameEnd = match.index + match[0].length
+    declarations.push({
+      name: match[6],
+      purity: match[4],
+      line: lineAt(source, match.index),
+      body: bodyRange(code, nameEnd)
+    })
+  }
+
+  return declarations
+}
+
+/*
+ * Static and name-based: a pure function may not mention a declared effect
+ * or an effectful function outside strings, comments, and property access.
+ */
+export function findPurityViolations(source) {
+  const code = maskNonCode(source)
+  const declarations = findPurityDeclarations(source)
+  const forbidden = [
+    ...findEffectDeclarations(source).map(declaration => ({ name: declaration.name, kind: 'effect' })),
+    ...declarations
+      .filter(declaration => declaration.purity === 'effectful')
+      .map(declaration => ({ name: declaration.name, kind: 'effectful function' }))
+  ]
+
+  return declarations
+    .filter(declaration => declaration.purity === 'pure')
+    .flatMap(declaration => {
+      const body = code.slice(declaration.body.start, declaration.body.end)
+
+      return forbidden
+        .filter(({ name }) => name !== declaration.name)
+        .map(({ name, kind }) => ({ kind, name, index: body.search(new RegExp(`(?<![.\\w$])${name}(?![\\w$])`)) }))
+        .filter(({ index }) => index !== -1)
+        .map(({ name, kind, index }) => ({
+          function: declaration.name,
+          uses: name,
+          kind,
+          line: lineAt(source, declaration.body.start + index)
+        }))
+    })
+    .sort((a, b) => a.line - b.line)
+}
+
+export function transformPurityModifiers(source) {
+  const violation = findPurityViolations(source)[0]
+  if (violation) {
+    throw new SyntaxError(`pure fn "${violation.function}" uses ${violation.kind} "${violation.uses}" (line ${violation.line})`)
+  }
+
+  const code = maskNonCode(source)
+  return source.replace(PURITY_DECLARATION, (match, ...args) => {
+    const offset = args[args.length - 2]
+    if (code.slice(offset, offset + match.length) !== match) return match
+    return match.replace(/(pure|effectful)[ \t]+(?=(?:async[ \t]+)?fn[ \t])/, '')
+  })
+}

package/src/runtime/checkpoint-store.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs'
-import path from 'node:path'
+import path from 'node:path'
+
+import { toJson, fromJson } from './serialization.js'
 
 /*
  * Storage interface for checkpoints. Deliberately storage-agnostic: the
@@ -102,7 +104,7 @@ export class FileCheckpointStore extends CheckpointStore {
     fs.mkdirSync(path.dirname(file), { recursive: true })
 
     const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
-    fs.writeFileSync(tmp, JSON.stringify(checkpoint), 'utf8')
+    fs.writeFileSync(tmp, toJson(checkpoint), 'utf8')
     fs.renameSync(tmp, file)
   }
 
@@ -112,7 +114,7 @@ export class FileCheckpointStore extends CheckpointStore {
 
     let checkpoint
     try {
-      checkpoint = JSON.parse(fs.readFileSync(file, 'utf8'))
+      checkpoint = fromJson(fs.readFileSync(file, 'utf8'))
     } catch (error) {
       throw new Error(`Corrupted checkpoint "${checkpointId}": ${error.message}`)
     }

package/src/runtime/checkpoint.js

@@ -1,4 +1,5 @@
-import { getCurrentContext, getDefaultContext } from './execution-context.js'
+import { getCurrentContext, getDefaultContext } from './execution-context.js'
+import { now } from './effects.js'
 
 /*
  * A pipeline checkpoint. `items` flow through unchanged; the operator's job
@@ -64,6 +65,6 @@ export async function* checkpoint(items, name, meta = {}) {
     checkpointId: name,
     items: buffer,
     itemCount: buffer.length,
-    createdAt: new Date().toISOString()
+    createdAt: new Date(now()).toISOString()
   })
 }

package/src/runtime/effects.js

@@ -25,6 +25,7 @@ import { getCurrentContext } from './execution-context.js'
 const handlerStorage = new AsyncLocalStorage()
 const invocationStorage = new AsyncLocalStorage()
 const authorizationStorage = new AsyncLocalStorage()
+const deterministicStorage = new AsyncLocalStorage()
 
 /*
  * name -> { name, params, sideEffecting, replayable, builtin? }.
@@ -70,6 +71,15 @@ export class EffectAuthorizationError extends Error {
   }
 }
 
+export class NondeterministicEffectError extends Error {
+  constructor(name) {
+    super(`Effect "${name}" has no deterministic handler; inside deterministic mode use { handle, deterministic: true } or replayHandlers`)
+    this.name = 'NondeterministicEffectError'
+    this.effectName = name
+    this.retryable = false
+  }
+}
+
 /*
  * Declares a named effect and returns the callable used to *perform* it.
  * `options.sideEffecting` (default true) and `options.replayable` (default
@@ -221,9 +231,13 @@ export async function performEffect(name, args) {
     throw new UnhandledEffectError(name)
   }
 
+  const entry = frame.handlers[name]
+  if (deterministicStorage.getStore() && entry.deterministic !== true) {
+    throw new NondeterministicEffectError(name)
+  }
+
   await authorizeEffect(name, args)
 
-  const entry = frame.handlers[name]
   const nextInFlight = new Set(inFlight)
   nextInFlight.add(name)
 
@@ -280,9 +294,65 @@ effectRegistry.set('PARALLEL', {
   builtin: true
 })
 
+for (const [name, params] of [['TIME', []], ['RANDOM', []]]) {
+  effectRegistry.set(name, { name, params, sideEffecting: false, replayable: false, builtin: true })
+}
+
+function builtinHandler(name) {
+  const frame = currentFrames().find(f => name in f.handlers)
+  return frame ? frame.handlers[name].handle : null
+}
+
 export function getParallelHandler() {
-  const frame = currentFrames().find(f => 'PARALLEL' in f.handlers)
-  return frame ? frame.handlers.PARALLEL.handle : null
+  return builtinHandler('PARALLEL')
+}
+
+/*
+ * `now()` and `random()` are built-in capabilities like `PARALLEL`: they are
+ * synchronous, fall back to `Date.now()` / `Math.random()`, and can be
+ * replaced with `handle { TIME: ..., RANDOM: ... }` or `deterministic()`.
+ */
+export function now() {
+  const handler = builtinHandler('TIME')
+  return handler ? handler() : Date.now()
+}
+
+export function random() {
+  const handler = builtinHandler('RANDOM')
+  return handler ? handler() : Math.random()
+}
+
+// mulberry32: a small, well-distributed seeded generator.
+function seededRandom(seed) {
+  let state = seed >>> 0
+  return () => {
+    state = (state + 0x6D2B79F5) >>> 0
+    let t = state
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+async function* runSequentially({ items, fn }) {
+  for await (const item of items) yield await fn(item)
+}
+
+/*
+ * Runs `fn` so that the same inputs always produce the same outputs: a seeded
+ * `random()`, a clock that starts at `startTime` and advances 1ms per read,
+ * sequential `parallel()`, and only effects whose handler is declared
+ * deterministic (including replay handlers).
+ */
+export function deterministic(fn, options = {}) {
+  let clock = options.startTime ?? 0
+  const handlers = {
+    TIME: { handle: () => clock++, deterministic: true },
+    RANDOM: { handle: seededRandom(options.seed ?? 1), deterministic: true },
+    PARALLEL: { handle: runSequentially, deterministic: true }
+  }
+
+  return deterministicStorage.run(true, () => withHandlers(handlers, fn))
 }
 
 /*

package/src/runtime/errors.js

@@ -27,3 +27,17 @@ export class PipelineError extends Error {
     this.timestamp = details.timestamp ?? new Date().toISOString()
   }
 }
+
+/*
+ * A broken `requires`/`ensures` clause is a programming error, so retrying
+ * the same call can never succeed.
+ */
+export class ContractError extends NonRetryableError {
+  constructor(functionName, kind, condition) {
+    super(`Contract violated: ${functionName} ${kind} ${condition}`)
+    this.name = 'ContractError'
+    this.functionName = functionName
+    this.kind = kind
+    this.condition = condition
+  }
+}

package/src/runtime/index.js

@@ -31,10 +31,12 @@ export {
 } from './collections.js'
 
 export { checkpoint } from './checkpoint.js'
+export { toJson, fromJson } from './serialization.js'
+export { defineType } from './tagged-unions.js'
 export { inspect, formatInspectReport } from './inspect.js'
 export { retry } from './retry.js'
 export { traceNode } from './trace.js'
-export { PipelineError, NonRetryableError } from './errors.js'
+export { PipelineError, NonRetryableError, ContractError } from './errors.js'
 export { Metrics, throughputOf } from './metrics.js'
 export {
   CheckpointStore,
@@ -62,7 +64,11 @@ export {
   UnhandledEffectError,
   EffectHandlerError,
   RecursiveEffectError,
-  EffectAuthorizationError
+  EffectAuthorizationError,
+  NondeterministicEffectError,
+  deterministic,
+  now,
+  random
 } from './effects.js'
 export {
   EffectLog,

package/src/runtime/mcp.js

@@ -159,7 +159,7 @@ export class McpServer {
   constructor({
     tools = {},
     name = 'JojoScript',
-    version = '0.10.1',
+    version = '1.0.0',
     protocolVersion = MCP_PROTOCOL_VERSION
   } = {}) {
     this.tools = new Map(

package/src/runtime/serialization.js

@@ -0,0 +1,97 @@
+/*
+ * Canonical JSON for JojoScript values. Object keys are sorted so equal
+ * values always produce identical text, and values plain JSON would lose
+ * are encoded as `{ "$type": ... }` objects. An ordinary object that has its
+ * own `$type` key is wrapped, so a tag is never ambiguous.
+ */
+export function toJson(value, options = {}) {
+  return JSON.stringify(encode(value, new Set()), null, options.indent)
+}
+
+export function fromJson(text) {
+  return decode(JSON.parse(text))
+}
+
+const ERROR_BUILT_INS = new Set(['name', 'message', 'stack', 'cause'])
+
+function encodeNumber(value) {
+  if (Number.isNaN(value) || !Number.isFinite(value) || Object.is(value, -0)) {
+    return { $type: 'Number', value: Object.is(value, -0) ? '-0' : String(value) }
+  }
+  return value
+}
+
+function encodeObject(value, ancestors) {
+  const result = {}
+  for (const key of Object.keys(value).sort()) result[key] = encode(value[key], ancestors)
+  return Object.hasOwn(value, '$type') ? { $type: 'Object', value: result } : result
+}
+
+function encodeError(error, ancestors) {
+  const fields = {}
+  for (const key of Object.keys(error).sort()) {
+    if (!ERROR_BUILT_INS.has(key)) fields[key] = encode(error[key], ancestors)
+  }
+
+  const encoded = { $type: 'Error', name: error.name, message: error.message, fields }
+  if ('cause' in error) encoded.cause = encode(error.cause, ancestors)
+  return encoded
+}
+
+function encode(value, ancestors) {
+  if (value === undefined) return { $type: 'undefined' }
+  if (typeof value === 'number') return encodeNumber(value)
+  if (typeof value === 'bigint') return { $type: 'BigInt', value: String(value) }
+  if (typeof value === 'function') throw new TypeError('Cannot serialize a function')
+  if (typeof value === 'symbol') throw new TypeError('Cannot serialize a symbol')
+  if (value === null || typeof value !== 'object') return value
+
+  if (ancestors.has(value)) throw new TypeError('Cannot serialize a circular structure')
+  ancestors.add(value)
+
+  try {
+    if (value instanceof Date) return { $type: 'Date', value: value.toISOString() }
+    if (value instanceof Map) {
+      return { $type: 'Map', entries: [...value].map(([key, item]) => [encode(key, ancestors), encode(item, ancestors)]) }
+    }
+    if (value instanceof Set) return { $type: 'Set', values: [...value].map(item => encode(item, ancestors)) }
+    if (value instanceof Error) return encodeError(value, ancestors)
+    if (Array.isArray(value)) return value.map(item => encode(item, ancestors))
+    if (typeof value.toJSON === 'function') return encode(value.toJSON(), ancestors)
+    return encodeObject(value, ancestors)
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function decodeEntries(object) {
+  const result = {}
+  for (const [key, item] of Object.entries(object)) result[key] = decode(item)
+  return result
+}
+
+function decodeError(encoded) {
+  const error = new Error(encoded.message)
+  error.name = encoded.name
+  Object.assign(error, decodeEntries(encoded.fields ?? {}))
+  if ('cause' in encoded) error.cause = decode(encoded.cause)
+  return error
+}
+
+function decode(value) {
+  if (Array.isArray(value)) return value.map(decode)
+  if (value === null || typeof value !== 'object') return value
+  if (!Object.hasOwn(value, '$type')) return decodeEntries(value)
+
+  switch (value.$type) {
+    case 'undefined': return undefined
+    case 'Number': return Number(value.value)
+    case 'BigInt': return BigInt(value.value)
+    case 'Date': return new Date(value.value)
+    case 'Map': return new Map(value.entries.map(([key, item]) => [decode(key), decode(item)]))
+    case 'Set': return new Set(value.values.map(decode))
+    case 'Error': return decodeError(value)
+    case 'Object': return decodeEntries(value.value)
+    default: throw new TypeError(`Unknown serialized type "${value.$type}"`)
+  }
+}

package/src/runtime/tagged-unions.js

@@ -0,0 +1,29 @@
+/*
+ * Tagged union values are frozen plain objects (`{ tag: "Ok", value: 1 }`),
+ * so they serialize to JSON and still match constructor patterns afterwards.
+ */
+export function defineType(typeName, variants) {
+  const constructors = {}
+
+  for (const [tag, fields] of Object.entries(variants)) {
+    if (fields.includes('tag')) {
+      throw new TypeError(`Variant "${tag}" cannot declare a field named "tag"`)
+    }
+
+    const construct = (...args) => {
+      if (args.length !== fields.length) {
+        const expected = fields.length === 1 ? '1 argument' : `${fields.length} arguments`
+        const names = fields.length ? ` (${fields.join(', ')})` : ''
+        throw new TypeError(`${tag} expects ${expected}${names}, got ${args.length}`)
+      }
+
+      const value = { tag }
+      fields.forEach((field, index) => { value[field] = args[index] })
+      return Object.freeze(value)
+    }
+
+    constructors[tag] = Object.assign(construct, { tag, type: typeName, fields: Object.freeze([...fields]) })
+  }
+
+  return Object.freeze(constructors)
+}