@mojir/dvala 0.0.1 → 0.0.2

package/dist/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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;

package/dist/src/evaluator/ContextStack.d.ts

@@ -0,0 +1,65 @@
+import type { Any } from '../interface';
+import type { ContextParams } from '../Dvala/Dvala';
+import type { DvalaModule } from '../builtin/modules/interface';
+import type { NativeJsFunction, SymbolNode, UserDefinedSymbolNode } from '../parser/types';
+import type { SourceCodeInfo } from '../tokenizer/token';
+import type { Context, LookUpResult } from './interface';
+export type ContextStack = ContextStackImpl;
+export declare class ContextStackImpl {
+    private _contexts;
+    globalContext: Context;
+    private values?;
+    private nativeJsFunctions?;
+    private modules;
+    private valueModules;
+    pure: boolean;
+    constructor({ contexts, values: hostValues, nativeJsFunctions, modules, valueModules, pure, }: {
+        contexts: Context[];
+        values?: Record<string, unknown>;
+        nativeJsFunctions?: Record<string, NativeJsFunction>;
+        modules?: Map<string, DvalaModule>;
+        valueModules?: Map<string, unknown>;
+        pure?: boolean;
+    });
+    /** Get the raw context chain for serialization. */
+    getContextsRaw(): Context[];
+    /** Get host values (plain bindings passed at creation). */
+    getHostValues(): Record<string, unknown> | undefined;
+    /**
+     * Find the index of globalContext in the _contexts array.
+     * Returns -1 if not found (should not happen in valid state).
+     */
+    getGlobalContextIndex(): number;
+    /**
+     * Create a ContextStack from deserialized data.
+     * `contexts` is the restored context chain (already resolved).
+     * `globalContextIndex` identifies which element is the globalContext.
+     * Host bindings (`values`, `nativeJsFunctions`, `modules`) come from resume options.
+     */
+    static fromDeserialized(params: {
+        contexts: Context[];
+        globalContextIndex: number;
+        values?: Record<string, unknown>;
+        nativeJsFunctions?: Record<string, NativeJsFunction>;
+        modules?: Map<string, DvalaModule>;
+        pure: boolean;
+    }): ContextStackImpl;
+    /**
+     * Replace the contexts array and globalContext. Used during deserialization
+     * to fill in resolved context data after circular references are handled.
+     */
+    setContextsFromDeserialized(contexts: Context[], globalContextIndex: number): void;
+    getModule(name: string): DvalaModule | undefined;
+    getValueModule(name: string): {
+        value: unknown;
+        found: boolean;
+    };
+    registerValueModule(name: string, value: unknown): void;
+    create(context: Context): ContextStack;
+    new(context: Context): ContextStack;
+    addValues(values: Record<string, Any>, sourceCodeInfo: SourceCodeInfo | undefined): void;
+    getValue(name: string): unknown;
+    lookUp(node: UserDefinedSymbolNode): LookUpResult;
+    evaluateSymbol(node: SymbolNode): Any;
+}
+export declare function createContextStack(params?: ContextParams, modules?: Map<string, DvalaModule>, pure?: boolean): ContextStack;

package/dist/src/evaluator/effectRef.d.ts

@@ -0,0 +1,27 @@
+/**
+ * EffectRef Interning
+ *
+ * Maintains a module-level intern map so that `getEffectRef('llm.complete')`
+ * always returns the exact same `EffectRef` object. This guarantees reference
+ * equality (`===`) for effect values created with the same name, which is
+ * important for handler matching in `try/with` blocks.
+ *
+ * EffectRef values are serializable — they are stored as just their name string.
+ * When a continuation is restored, the name is used to look up (or recreate)
+ * the unique EffectRef in the new runtime.
+ */
+import type { EffectRef } from '../parser/types';
+/**
+ * Returns the unique EffectRef for the given name.
+ * Calling with the same name always returns the same reference.
+ *
+ * @example
+ * const a = getEffectRef('llm.complete')
+ * const b = getEffectRef('llm.complete')
+ * a === b // true
+ */
+export declare function getEffectRef(name: string): EffectRef;
+/**
+ * Clears the intern map. Primarily for testing.
+ */
+export declare function clearEffectRefInternMap(): void;

package/dist/src/evaluator/effectTypes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared types for the algebraic effects system.
+ *
+ * This module exists to break the circular dependency between `effects.ts`
+ * (standalone functions) and `evaluator/trampoline.ts` (trampoline loop).
+ * Both modules import types from here without creating a cycle.
+ */
+import type { Any } from '../interface';
+import type { DvalaError } from '../errors';
+import type { ContinuationStack } from './frames';
+/**
+ * Opaque string containing the serialized continuation stack.
+ * Created by `suspend()`, consumed by `resume()`.
+ * Internally it's JSON, but hosts should treat it as opaque.
+ */
+export type SuspensionBlob = string;
+/**
+ * Context passed to a host effect handler.
+ *
+ * The handler must call exactly one of `resume` or `suspend`, exactly once.
+ * Calling both, or calling either more than once, is a programming error.
+ */
+export interface EffectContext {
+    /** Arguments from the Dvala `perform(eff, arg1, arg2, ...)` call. */
+    args: Any[];
+    /**
+     * Aborted when: `race()` branch loses, runtime is disposed, or host cancels.
+     * Combine with timeout: `AbortSignal.any([signal, AbortSignal.timeout(ms)])`
+     */
+    signal: AbortSignal;
+    /**
+     * Resume the program with the given value (or a Promise that resolves to one).
+     * The value becomes the result of the `perform(...)` expression in Dvala.
+     */
+    resume: (value: Any | Promise<Any>) => void;
+    /**
+     * Suspend the program. The entire execution state is captured and returned
+     * in `RunResult` as `{ type: 'suspended', continuation, meta }`.
+     * `meta` is passed through to `RunResult.meta` for domain context
+     * (e.g., assignee, deadline, priority).
+     */
+    suspend: (meta?: Any) => void;
+}
+/** An async function that handles an effect by calling `resume` or `suspend`. */
+export type EffectHandler = (ctx: EffectContext) => Promise<void>;
+/** Map from effect name (e.g. `'llm.complete'`) to its handler. */
+export type Handlers = Record<string, EffectHandler>;
+/**
+ * The result of `run()` — always resolves, never rejects.
+ * Errors are captured in the `error` variant.
+ */
+export type RunResult = {
+    type: 'completed';
+    value: Any;
+} | {
+    type: 'suspended';
+    blob: SuspensionBlob;
+    meta?: Any;
+} | {
+    type: 'error';
+    error: DvalaError;
+};
+/**
+ * Thrown (as a promise rejection) by `suspend()` inside a host handler.
+ * Caught by the effect trampoline loop — NOT by Dvala-level try/catch.
+ */
+export declare class SuspensionSignal {
+    /** The captured continuation stack at the point of suspension. */
+    readonly k: ContinuationStack;
+    /** Optional domain metadata passed through to RunResult. */
+    readonly meta?: Any | undefined;
+    readonly _brand: "SuspensionSignal";
+    constructor(
+    /** The captured continuation stack at the point of suspension. */
+    k: ContinuationStack, 
+    /** Optional domain metadata passed through to RunResult. */
+    meta?: Any | undefined);
+}
+export declare function isSuspensionSignal(value: unknown): value is SuspensionSignal;