@mojir/dvala 0.0.1 → 0.0.2

package/dist/modules/src/builtin/modules/vector/reductionFunctions/index.d.ts

@@ -0,0 +1,13 @@
+import type { BuiltinNormalExpressions } from '../../../../builtin/interface';
+type VectorReductionKey<T extends string> = `${T}`;
+type VectorMovingWindowKey<T extends string> = `moving-${T}`;
+type VectorCenteredMovingWindowKey<T extends string> = `centered-moving-${T}`;
+type VectorRunningKey<T extends string> = `running-${T}`;
+export type VectorReductionKeys<T extends string> = VectorReductionKey<T> | VectorMovingWindowKey<T> | VectorCenteredMovingWindowKey<T> | VectorRunningKey<T>;
+type ReductionFunction = (vector: number[]) => number;
+export type ReductionFunctionDefinition<T extends string> = Record<VectorReductionKey<T>, ReductionFunction> & {
+    minLength?: number;
+    padding?: number;
+};
+export declare const reductionFunctionNormalExpressions: BuiltinNormalExpressions;
+export {};

package/dist/modules/src/builtin/modules/vector/reductionFunctions/iqr.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const iqrReductionFunction: ReductionFunctionDefinition<'iqr'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/kurtosis.d.ts

@@ -0,0 +1,5 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const kurtosisReductionFunction: ReductionFunctionDefinition<'kurtosis'>;
+export declare const eccessKurtosisReductionFunction: ReductionFunctionDefinition<'excess-kurtosis'>;
+export declare const sampleKurtosisReductionFunction: ReductionFunctionDefinition<'sample-kurtosis'>;
+export declare const sampleExcessKurtosisReductionFunction: ReductionFunctionDefinition<'sample-excess-kurtosis'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/mad.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const madReductionFunction: ReductionFunctionDefinition<'mad'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/mean.d.ts

@@ -0,0 +1,4 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const meanReductionFunction: ReductionFunctionDefinition<'mean'>;
+export declare const geometricMeanReductionFunction: ReductionFunctionDefinition<'geometric-mean'>;
+export declare const harmonicMeanReductionFunction: ReductionFunctionDefinition<'harmonic-mean'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/medad.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const medadReductionFunction: ReductionFunctionDefinition<'medad'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/median.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const medianReductionFunction: ReductionFunctionDefinition<'median'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/prod.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const prodReductionFunction: ReductionFunctionDefinition<'prod'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/rms.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const rmsReductionFunction: ReductionFunctionDefinition<'rms'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/skewness.d.ts

@@ -0,0 +1,3 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const skewnessReductionFunction: ReductionFunctionDefinition<'skewness'>;
+export declare const sampleSkewnessReductionFunction: ReductionFunctionDefinition<'sample-skewness'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/span.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const spanReductionFunction: ReductionFunctionDefinition<'span'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/standardDeviation.d.ts

@@ -0,0 +1,3 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const stdevReductionFunction: ReductionFunctionDefinition<'stdev'>;
+export declare const sampleStdevReductionFunction: ReductionFunctionDefinition<'sample-stdev'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/sum.d.ts

@@ -0,0 +1,2 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const sumReductionFunction: ReductionFunctionDefinition<'sum'>;

package/dist/modules/src/builtin/modules/vector/reductionFunctions/variance.d.ts

@@ -0,0 +1,3 @@
+import type { ReductionFunctionDefinition } from '.';
+export declare const varianceReductionFunction: ReductionFunctionDefinition<'variance'>;
+export declare const sampleVarianceReductionFunction: ReductionFunctionDefinition<'sample-variance'>;

package/dist/modules/src/builtin/normalExpressions/index.d.ts

@@ -0,0 +1,8 @@
+import type { BuiltinNormalExpression, BuiltinNormalExpressions } from '../interface';
+import type { Any } from '../../interface';
+import type { FunctionReference } from '../../../reference';
+import type { CoreNormalExpressionName } from '../../../reference/api';
+export declare function setNormalExpressionReference(reference: Record<CoreNormalExpressionName, FunctionReference>): void;
+export declare const normalExpressions: BuiltinNormalExpressions;
+export declare const normalExpressionTypes: Record<string, number>;
+export declare const allNormalExpressions: BuiltinNormalExpression<Any>[];

package/dist/modules/src/builtin/specialExpressionTypes.d.ts

@@ -0,0 +1,26 @@
+export declare const specialExpressionTypes: {
+    readonly '??': 0;
+    readonly '&&': 1;
+    readonly '||': 2;
+    readonly array: 3;
+    readonly cond: 4;
+    readonly 'defined?': 5;
+    readonly block: 6;
+    readonly doseq: 7;
+    readonly '0_lambda': 8;
+    readonly for: 9;
+    readonly if: 10;
+    readonly let: 11;
+    readonly loop: 12;
+    readonly object: 13;
+    readonly recur: 14;
+    readonly match: 15;
+    readonly throw: 16;
+    readonly try: 17;
+    readonly unless: 18;
+    readonly import: 19;
+    readonly effect: 20;
+    readonly perform: 21;
+    readonly parallel: 22;
+    readonly race: 23;
+};

package/dist/modules/src/builtin/specialExpressions/and.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type AndNode = SpecialExpressionNode<[typeof specialExpressionTypes['&&'], AstNode[]]>;
+export declare const andSpecialExpression: BuiltinSpecialExpression<Any, AndNode>;

package/dist/modules/src/builtin/specialExpressions/array.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type ArrayNode = SpecialExpressionNode<[typeof specialExpressionTypes['array'], AstNode[]]>;
+export declare const arraySpecialExpression: BuiltinSpecialExpression<Any, ArrayNode>;

package/dist/modules/src/builtin/specialExpressions/block.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type DoNode = SpecialExpressionNode<[typeof specialExpressionTypes['block'], AstNode[]]>;
+export declare const doSpecialExpression: BuiltinSpecialExpression<Any, DoNode>;

package/dist/modules/src/builtin/specialExpressions/cond.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type CondNode = SpecialExpressionNode<[typeof specialExpressionTypes['cond'], [AstNode, AstNode][]]>;
+export declare const condSpecialExpression: BuiltinSpecialExpression<Any, CondNode>;

package/dist/modules/src/builtin/specialExpressions/defined.d.ts

@@ -0,0 +1,5 @@
+import type { SpecialExpressionNode, SymbolNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type DefinedNode = SpecialExpressionNode<[typeof specialExpressionTypes['defined?'], SymbolNode]>;
+export declare const definedSpecialExpression: BuiltinSpecialExpression<boolean, DefinedNode>;

package/dist/modules/src/builtin/specialExpressions/effect.d.ts

@@ -0,0 +1,5 @@
+import type { EffectRef, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type EffectNode = SpecialExpressionNode<[typeof specialExpressionTypes['effect'], string]>;
+export declare const effectSpecialExpression: BuiltinSpecialExpression<EffectRef, EffectNode>;

package/dist/modules/src/builtin/specialExpressions/functions.d.ts

@@ -0,0 +1,6 @@
+import type { DvalaFunction, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { Function } from '../utils';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type LambdaNode = SpecialExpressionNode<[typeof specialExpressionTypes['0_lambda'], Function, string]>;
+export declare const lambdaSpecialExpression: BuiltinSpecialExpression<DvalaFunction, LambdaNode>;

package/dist/modules/src/builtin/specialExpressions/if.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type IfNode = SpecialExpressionNode<[typeof specialExpressionTypes['if'], [AstNode, AstNode, AstNode?]]>;
+export declare const ifSpecialExpression: BuiltinSpecialExpression<Any, IfNode>;

package/dist/modules/src/builtin/specialExpressions/import.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type ImportNode = SpecialExpressionNode<[typeof specialExpressionTypes['import'], string]>;
+export declare const importSpecialExpression: BuiltinSpecialExpression<Any, ImportNode>;

package/dist/modules/src/builtin/specialExpressions/let.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { BindingNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type LetNode = SpecialExpressionNode<[typeof specialExpressionTypes['let'], BindingNode]>;
+export declare const letSpecialExpression: BuiltinSpecialExpression<Any, LetNode>;

package/dist/modules/src/builtin/specialExpressions/loop.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, BindingNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type LoopNode = SpecialExpressionNode<[typeof specialExpressionTypes['loop'], BindingNode[], AstNode]>;
+export declare const loopSpecialExpression: BuiltinSpecialExpression<Any, LoopNode>;

package/dist/modules/src/builtin/specialExpressions/loops.d.ts

@@ -0,0 +1,9 @@
+import type { Any } from '../../interface';
+import type { AstNode, BindingNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type LoopBindingNode = [BindingNode, BindingNode[], AstNode?, AstNode?];
+export type ForNode = SpecialExpressionNode<[typeof specialExpressionTypes['for'], LoopBindingNode[], AstNode]>;
+export type DoSeqNode = SpecialExpressionNode<[typeof specialExpressionTypes['doseq'], LoopBindingNode[], AstNode]>;
+export declare const forSpecialExpression: BuiltinSpecialExpression<Any, ForNode>;
+export declare const doseqSpecialExpression: BuiltinSpecialExpression<null, DoSeqNode>;

package/dist/modules/src/builtin/specialExpressions/match.d.ts

@@ -0,0 +1,7 @@
+import type { Any } from '../../interface';
+import type { AstNode, BindingTarget, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type MatchCase = [BindingTarget, AstNode, AstNode | undefined];
+export type MatchNode = SpecialExpressionNode<[typeof specialExpressionTypes['match'], AstNode, MatchCase[]]>;
+export declare const matchSpecialExpression: BuiltinSpecialExpression<Any, MatchNode>;

package/dist/modules/src/builtin/specialExpressions/object.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type ObjectNode = SpecialExpressionNode<[typeof specialExpressionTypes['object'], AstNode[]]>;
+export declare const objectSpecialExpression: BuiltinSpecialExpression<Any, ObjectNode>;

package/dist/modules/src/builtin/specialExpressions/or.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type OrNode = SpecialExpressionNode<[typeof specialExpressionTypes['||'], AstNode[]]>;
+export declare const orSpecialExpression: BuiltinSpecialExpression<Any, OrNode>;

package/dist/modules/src/builtin/specialExpressions/parallel.d.ts

@@ -0,0 +1,6 @@
+import type { Arr } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type ParallelNode = SpecialExpressionNode<[typeof specialExpressionTypes['parallel'], AstNode[]]>;
+export declare const parallelSpecialExpression: BuiltinSpecialExpression<Arr, ParallelNode>;

package/dist/modules/src/builtin/specialExpressions/perform.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type PerformNode = SpecialExpressionNode<[typeof specialExpressionTypes['perform'], AstNode, AstNode[]]>;
+export declare const performSpecialExpression: BuiltinSpecialExpression<Any, PerformNode>;

package/dist/modules/src/builtin/specialExpressions/qq.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type QqNode = SpecialExpressionNode<[typeof specialExpressionTypes['??'], AstNode[]]>;
+export declare const qqSpecialExpression: BuiltinSpecialExpression<Any, QqNode>;

package/dist/modules/src/builtin/specialExpressions/race.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type RaceNode = SpecialExpressionNode<[typeof specialExpressionTypes['race'], AstNode[]]>;
+export declare const raceSpecialExpression: BuiltinSpecialExpression<Any, RaceNode>;

package/dist/modules/src/builtin/specialExpressions/recur.d.ts

@@ -0,0 +1,5 @@
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type RecurNode = SpecialExpressionNode<[typeof specialExpressionTypes['recur'], AstNode[]]>;
+export declare const recurSpecialExpression: BuiltinSpecialExpression<null, RecurNode>;

package/dist/modules/src/builtin/specialExpressions/throw.d.ts

@@ -0,0 +1,5 @@
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type ThrowNode = SpecialExpressionNode<[typeof specialExpressionTypes['throw'], AstNode]>;
+export declare const throwSpecialExpression: BuiltinSpecialExpression<null, ThrowNode>;

package/dist/modules/src/builtin/specialExpressions/try.d.ts

@@ -0,0 +1,7 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode, SymbolNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type WithHandler = [AstNode, AstNode];
+export type TryNode = SpecialExpressionNode<[typeof specialExpressionTypes['try'], AstNode, SymbolNode | undefined, AstNode | undefined, WithHandler[]]>;
+export declare const trySpecialExpression: BuiltinSpecialExpression<Any, TryNode>;

package/dist/modules/src/builtin/specialExpressions/unless.d.ts

@@ -0,0 +1,6 @@
+import type { Any } from '../../interface';
+import type { AstNode, SpecialExpressionNode } from '../../parser/types';
+import type { BuiltinSpecialExpression } from '../interface';
+import type { specialExpressionTypes } from '../specialExpressionTypes';
+export type UnlessNode = SpecialExpressionNode<[typeof specialExpressionTypes['unless'], [AstNode, AstNode, AstNode?]]>;
+export declare const unlessSpecialExpression: BuiltinSpecialExpression<Any, UnlessNode>;

package/dist/modules/src/builtin/utils.d.ts

@@ -0,0 +1,6 @@
+import type { ContextStack } from '../evaluator/ContextStack';
+import type { AstNode, BindingTarget } from '../parser/types';
+import type { SourceCodeInfo } from '../tokenizer/token';
+import type { Builtin } from './interface';
+export type Function = [BindingTarget[], AstNode[]];
+export declare function assertNameNotDefined<T>(name: T, contextStack: ContextStack, builtin: Builtin, sourceCodeInfo?: SourceCodeInfo): asserts name is T;

package/dist/modules/src/bundler/index.d.ts

@@ -0,0 +1,9 @@
+import type { DvalaBundle } from './interface';
+/**
+ * Bundles a Dvala entry file and all its file imports into a DvalaBundle.
+ *
+ * Resolves all `import("./path/to/file.dvala")` calls recursively,
+ * deduplicates, detects circular dependencies, topologically sorts,
+ * and rewrites file imports to bare symbol imports.
+ */
+export declare function bundle(entryPath: string): DvalaBundle;

package/dist/modules/src/bundler/interface.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A bundle produced by the bundler. Contains the main program source
+ * with file imports rewritten to canonical module names, plus an ordered
+ * array of file module sources keyed by canonical name.
+ *
+ * The bundle is pure JSON — fully serializable and portable
+ * (e.g., build on a server, run in a browser).
+ */
+export interface DvalaBundle {
+    /** The main program source, with file imports rewritten to bare symbols. */
+    program: string;
+    /** Ordered array of [canonicalName, source] pairs. Dependencies come before dependents. */
+    fileModules: [string, string][];
+}
+export declare function isDvalaBundle(value: unknown): value is DvalaBundle;

package/dist/modules/src/bundler.d.ts

@@ -0,0 +1,3 @@
+export { bundle } from './bundler/index';
+export type { DvalaBundle } from './bundler/interface';
+export { isDvalaBundle } from './bundler/interface';

package/dist/modules/src/constants/constants.d.ts

@@ -0,0 +1,19 @@
+export declare const NodeTypes: {
+    readonly Number: 1;
+    readonly String: 2;
+    readonly NormalExpression: 3;
+    readonly SpecialExpression: 4;
+    readonly UserDefinedSymbol: 5;
+    readonly NormalBuiltinSymbol: 6;
+    readonly SpecialBuiltinSymbol: 7;
+    readonly ReservedSymbol: 8;
+    readonly Binding: 9;
+    readonly Spread: 10;
+};
+export type NodeType = typeof NodeTypes[keyof typeof NodeTypes];
+export declare function getNodeTypeName(type: NodeType): keyof typeof NodeTypes;
+export declare function isNodeType(type: unknown): type is NodeType;
+declare const functionTypes: readonly ["UserDefined", "Partial", "Comp", "Constantly", "Juxt", "Complement", "EveryPred", "SomePred", "Fnull", "Builtin", "SpecialBuiltin", "NativeJsFunction", "Module"];
+export type FunctionType = typeof functionTypes[number];
+export declare function isFunctionType(type: unknown): type is FunctionType;
+export {};

package/dist/modules/src/debug.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Time-travel debugger for Dvala.
+ *
+ * Entry point: `@mojir/dvala/debug`
+ *
+ * Creates a debugger that intercepts every compound expression evaluation,
+ * recording the full execution state as serializable blobs. This enables:
+ * - Step forward/backward through execution
+ * - Jump to any point in history
+ * - Re-run from any step with an alternate value (alternate timelines)
+ * - Performance profiling via timestamps
+ *
+ * Usage:
+ * ```typescript
+ * import { createDebugger } from '@mojir/dvala/debug'
+ *
+ * const dbg = createDebugger({ handlers })
+ * await dbg.run(source)
+ * await dbg.stepForward()
+ * await dbg.stepBackward()
+ * await dbg.jumpTo(5)
+ * await dbg.rerunFrom(3, 0.42) // alternate timeline
+ * ```
+ */
+import type { Any } from './interface';
+import type { DvalaModule } from './builtin/modules/interface';
+import type { Handlers, RunResult, SuspensionBlob } from './evaluator/effectTypes';
+/**
+ * Information about a single evaluation step.
+ * Provided in each `HistoryEntry` for UI display and inspection.
+ */
+export interface StepInfo {
+    /** Source code line where the expression appears. */
+    expression: string;
+    /** The value produced by evaluating this expression. */
+    value: Any;
+    /** Source location of the expression. */
+    location: {
+        line: number;
+        column: number;
+    };
+    /** All in-scope bindings at this point in execution. */
+    env: Record<string, Any>;
+}
+/**
+ * A single entry in the debugger's execution history.
+ * Contains the serialized continuation (for resuming) and step info (for UI).
+ */
+export interface HistoryEntry {
+    /** Serialized continuation at this point — opaque to host. */
+    blob: SuspensionBlob;
+    /** Step info for UI display: expression, value, location, bindings. */
+    step: StepInfo;
+    /** Milliseconds since epoch — enables performance profiling. */
+    timestamp: number;
+}
+/**
+ * Options for creating a debugger instance.
+ */
+export interface DebuggerOptions {
+    /** Host effect handlers (e.g., 'llm.complete'). */
+    handlers?: Handlers;
+    /** Plain value bindings accessible from Dvala code. */
+    bindings?: Record<string, Any>;
+    /** Dvala modules to make available via import. */
+    modules?: DvalaModule[];
+}
+/**
+ * The Dvala time-travel debugger interface.
+ *
+ * After `run(source)`, the debugger pauses at the first debug step.
+ * Use `stepForward`/`stepBackward`/`jumpTo` to navigate execution history.
+ * Use `rerunFrom` to explore alternate timelines.
+ */
+export interface DvalaDebugger {
+    /** Run a Dvala program in debug mode. Pauses at the first debug step. */
+    run: (source: string) => Promise<RunResult>;
+    /** Advance one step forward in execution. */
+    stepForward: () => Promise<RunResult>;
+    /** Go back one step in execution history. */
+    stepBackward: () => Promise<RunResult>;
+    /** Jump to a specific step in history. */
+    jumpTo: (index: number) => Promise<RunResult>;
+    /**
+     * Re-run from a specific step with an alternate value.
+     * Discards history after the given index — creates a new timeline.
+     */
+    rerunFrom: (index: number, alternateValue: Any) => Promise<RunResult>;
+    /** The complete execution history. */
+    readonly history: HistoryEntry[];
+    /** The index of the current step in history. */
+    readonly currentStep: number;
+    /** The current history entry (shorthand for `history[currentStep]`). */
+    readonly current: HistoryEntry | undefined;
+}
+/**
+ * Create a time-travel debugger instance.
+ *
+ * The debugger intercepts every compound expression evaluation by injecting
+ * a `dvala.debug.step` effect handler that suspends at each step. Each
+ * suspension captures the full execution state as a serializable blob,
+ * enabling forward/backward navigation and alternate timelines.
+ *
+ * ```typescript
+ * const dbg = createDebugger({
+ *   handlers: {
+ *     'llm.complete': async ({ args, resume }) => resume('mocked')
+ *   }
+ * })
+ * await dbg.run(source)
+ * await dbg.stepForward()
+ * await dbg.stepBackward()
+ * ```
+ */
+export declare function createDebugger(options?: DebuggerOptions): DvalaDebugger;

package/dist/modules/src/effects.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Algebraic effects — host-facing API.
+ *
+ * Top-level standalone functions for running Dvala programs with effect handlers.
+ *
+ * Three levels of use:
+ * 1. `runSync(source, options?)` — pure computation, sync JS functions in bindings.
+ * 2. `run(source, options?)` — async effects with handlers, always completes or suspends.
+ * 3. `resume(blob, value, options?)` — resume a suspended continuation (Phase 4).
+ *
+ * Effect handlers are JavaScript functions that receive an `EffectContext` and must
+ * call exactly one of `resume(value)` or `suspend(meta?)`:
+ *
+ * ```typescript
+ * handlers: {
+ *   'llm.complete': async ({ args, signal, resume }) => {
+ *     resume(await callLLM(args[0], signal))
+ *   }
+ * }
+ * ```
+ */
+import type { Any } from './interface';
+import type { DvalaModule } from './builtin/modules/interface';
+import type { Handlers, RunResult } from './evaluator/effectTypes';
+export type { EffectContext, EffectHandler, SuspensionBlob } from './evaluator/effectTypes';
+export { SuspensionSignal, isSuspensionSignal } from './evaluator/effectTypes';
+export type { Handlers, RunResult } from './evaluator/effectTypes';
+/**
+ * Options for `run()` — async execution with effect handlers.
+ * `bindings` are plain values only (no JS functions).
+ * All host interaction goes through `handlers`.
+ */
+export interface RunOptions {
+    bindings?: Record<string, Any>;
+    handlers?: Handlers;
+    modules?: DvalaModule[];
+}
+/**
+ * Options for `runSync()` — synchronous pure computation.
+ * `bindings` may include JS functions (they become NativeJsFunctions).
+ */
+export interface RunSyncOptions {
+    bindings?: Record<string, unknown>;
+    modules?: DvalaModule[];
+}
+/**
+ * Options for `resume()` — resume a suspended continuation.
+ * `bindings` are plain values only (no JS functions).
+ * All host interaction goes through `handlers`.
+ * `modules` must be provided again (they are not in the blob).
+ */
+export interface ResumeOptions {
+    bindings?: Record<string, Any>;
+    handlers?: Handlers;
+    modules?: DvalaModule[];
+}
+/**
+ * Level 1: Pure synchronous computation.
+ *
+ * JS functions are allowed in `bindings` — they become NativeJsFunctions.
+ * Throws if an async operation or effect is encountered.
+ *
+ * ```typescript
+ * const value = runSync('[1, 2, 3] |> map(_, -> $ * $)')
+ * ```
+ */
+export declare function runSync(source: string, options?: RunSyncOptions): Any;
+/**
+ * Level 2 & 3: Async execution with effect handler support.
+ *
+ * `bindings` are plain values only (no JS functions).
+ * All host interaction goes through `handlers`.
+ * Always resolves — never rejects. Errors are in `RunResult`.
+ *
+ * ```typescript
+ * const result = await run(source, {
+ *   handlers: {
+ *     'llm.complete': async ({ args, resume }) => {
+ *       resume(await callLLM(args[0]))
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function run(source: string, options?: RunOptions): Promise<RunResult>;
+/**
+ * Level 3: Resume a suspended continuation.
+ *
+ * Takes a blob from a previous `RunResult` of type `'suspended'`, a resume
+ * value, and optional handlers/bindings. Re-enters the trampoline at the
+ * point of suspension with the provided value.
+ *
+ * `bindings` are plain values only (no JS functions). They are re-injected
+ * into the deserialized ContextStacks so that host-bound values remain
+ * accessible after resume. `modules` must be provided again if the Dvala
+ * program uses `import`.
+ *
+ * Always resolves — never rejects. May return `completed`, `suspended`
+ * (if another suspend is hit), or `error`.
+ *
+ * ```typescript
+ * const blob = suspendedResult.blob
+ * const next = await resume(blob, humanDecision, { handlers })
+ * ```
+ */
+export declare function resume(blob: string, value: Any, options?: ResumeOptions): Promise<RunResult>;

package/dist/modules/src/errors.d.ts

@@ -0,0 +1,24 @@
+import type { Arr } from './interface';
+import type { SourceCodeInfo } from './tokenizer/token';
+export declare class RecurSignal extends Error {
+    params: Arr;
+    constructor(params: Arr);
+}
+export declare class DvalaError extends Error {
+    readonly sourceCodeInfo?: SourceCodeInfo;
+    readonly shortMessage: string;
+    constructor(err: unknown, sourceCodeInfo: SourceCodeInfo | undefined);
+    getCodeMarker(): string | undefined;
+}
+export declare class UserDefinedError extends DvalaError {
+    userMessage: string;
+    constructor(message: string, sourceCodeInfo?: SourceCodeInfo);
+}
+export declare class AssertionError extends DvalaError {
+    constructor(message: string | Error, sourceCodeInfo?: SourceCodeInfo);
+}
+export declare class UndefinedSymbolError extends DvalaError {
+    symbol: string;
+    constructor(symbolName: string, sourceCodeInfo?: SourceCodeInfo);
+}
+export declare function isDvalaError(error: unknown): error is DvalaError;