Lineage & Source Maps

OriginTS tracks the provenance of every value through its lineage system. Every transformation step is recorded. Lineage is available regardless of success or failure.

Runtime lineage

A provenance graph built during execution. Records inputs, outputs, and transformations at each step.

import { run } from '@origints/core'

const result = await run(plan)
// result.lineage is always available, even on failure

Formatting lineage

Structured format

formatLineage produces a structured summary of each execution step with optional data previews:

import { formatLineage } from '@origints/core'

const formatted = formatLineage(result.lineage, plan.ast)

// formatted.steps[0].type === 'source'
// formatted.steps[0].output === '{"name":"Alice"}'

Step types include source, transform, emit, merge, and match.

String format

formatLineageAsString returns a multi-line string suitable for logging or debugging:

import { formatLineageAsString } from '@origints/core'

const str = formatLineageAsString(result.lineage, plan.ast)
console.log(str)
// Pipeline Execution (3 steps)
//   Step 1: SOURCE ...
//   Step 2: TRANSFORM ...
//   Step 3: EMIT ...

Source maps

Derive a flat record mapping each output path to its origin. Two modes are available:

Static source maps

Uses [*] wildcards for array positions. No execution needed.

import { deriveSourceMap, formatSourceMap } from '@origints/core'

const map = deriveSourceMap(plan.ast)
// map['name'] === { source: 'direct', transforms: [], inputPath: 'name', extractType: 'string' }

const formatted = formatSourceMap(map)
// formatted['name'] === 'direct → name as string'

Runtime source maps

Concrete array indices, only actually-run branches. Requires lineage from execution.

import { deriveRuntimeSourceMap } from '@origints/core'

const runtimeMap = deriveRuntimeSourceMap(result.lineage, plan.ast)

Source maps through output transforms

Source maps are remapped through mapOut transforms, so output paths correctly trace back through grouping, renaming, and other structural changes.