@mojir/dvala 0.0.10 → 0.0.12

package/dist/mcp-server/src/evaluator/frames.d.ts

@@ -1,513 +0,0 @@
-/**
- * Frame types for the trampoline evaluator.
- *
- * Each frame type represents a continuation — "what to do with the result of a
- * sub-evaluation." When the trampoline evaluates a sub-expression, it pushes a
- * frame onto the continuation stack (k). When the sub-expression produces a
- * value, the trampoline pops the frame and calls `applyFrame(frame, value, k)`
- * to determine the next step.
- *
- * All frame types are plain serializable objects — no functions, no closures.
- * This enables continuation serialization in Phase 4 (suspension & resume).
- *
- * The `env` field uses `ContextStack` for Phase 1 runtime use. In Phase 4,
- * this will be replaced with a serializable representation (the `Context[]`
- * chain without host bindings, which are re-injected on resume).
- */
-import type { Any, Arr, Obj } from '../interface';
-import type { DvalaModule } from '../builtin/modules/interface';
-import type { AstNode, BindingNode, BindingTarget, NormalExpressionNode, UserDefinedFunction } from '../parser/types';
-import type { MatchCase } from '../builtin/specialExpressions/match';
-import type { LoopBindingNode } from '../builtin/specialExpressions/loops';
-import type { SourceCodeInfo } from '../tokenizer/token';
-import type { ContextStack } from './ContextStack';
-import type { Snapshot } from './effectTypes';
-import type { Context } from './interface';
-/**
- * Evaluate a sequence of AST nodes in order, returning the last value.
- *
- * Used by: `do...end` (block), top-level program evaluation, function body.
- *
- * The trampoline evaluates `nodes[index]`. When the value comes back it
- * advances `index`. When all nodes are done, the last value propagates up.
- */
-export interface SequenceFrame {
-    type: 'Sequence';
-    nodes: AstNode[];
-    index: number;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Binary conditional branch — used by both `if` and `unless`.
- *
- * Pushed when the condition expression is being evaluated. When the condition
- * value arrives, the trampoline picks `thenNode` or `elseNode` (or returns
- * `null` if there is no else branch). `inverted` flips the test for `unless`.
- */
-export interface IfBranchFrame {
-    type: 'IfBranch';
-    thenNode: AstNode;
-    elseNode: AstNode | undefined;
-    inverted: boolean;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Multi-way conditional (`cond`).
- *
- * When `phase` is `'test'`: a test expression is being evaluated. If truthy,
- * transition to body evaluation. If falsy, advance to the next case.
- * When `phase` is `'body'`: the body expression is being evaluated. The
- * resulting value propagates up.
- */
-export interface CondFrame {
-    type: 'Cond';
-    phase: 'test' | 'body';
-    cases: [AstNode, AstNode][];
-    index: number;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Pattern matching (`match`).
- *
- * Phase `'matchValue'`: the match-value expression is being evaluated.
- * Phase `'guard'`: a pattern matched and boundary bindings were created;
- *   the guard expression is being evaluated.
- * Phase `'body'`: the body for the matched case is being evaluated.
- *
- * `matchValue` is `null` during the `'matchValue'` phase and set once known.
- * `bindings` holds the names captured by `tryMatch` (empty until a pattern
- * matches).
- */
-export interface MatchFrame {
-    type: 'Match';
-    phase: 'matchValue' | 'guard' | 'body';
-    matchValue: Any | null;
-    cases: MatchCase[];
-    index: number;
-    bindings: Record<string, Any>;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Short-circuit `&&` — evaluates nodes sequentially, returning the first
- * falsy value or the last value if all are truthy.
- */
-export interface AndFrame {
-    type: 'And';
-    nodes: AstNode[];
-    index: number;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Short-circuit `||` — evaluates nodes sequentially, returning the first
- * truthy value or the last value if all are falsy.
- */
-export interface OrFrame {
-    type: 'Or';
-    nodes: AstNode[];
-    index: number;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Nullish coalescing `??` — evaluates nodes sequentially, returning the
- * first non-null value. Undefined user-defined symbols are treated as null
- * (skipped without throwing `UndefinedSymbolError`).
- */
-export interface QqFrame {
-    type: 'Qq';
-    nodes: AstNode[];
-    index: number;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Array literal construction (`[]` / `array`).
- *
- * Evaluates elements sequentially. Spread nodes (`...expr`) evaluate the
- * inner expression and flatten the resulting array into `result`.
- */
-export interface ArrayBuildFrame {
-    type: 'ArrayBuild';
-    nodes: AstNode[];
-    index: number;
-    result: Arr;
-    isSpread: boolean;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Object literal construction (`{}` / `object`).
- *
- * Evaluates key-value pairs sequentially. For normal entries, evaluates
- * key then value (stepping by 2). For spread entries, evaluates the spread
- * expression and merges the result into `result`.
- *
- * `currentKey` holds the evaluated key string when we're between key and
- * value evaluation (null otherwise).
- */
-export interface ObjectBuildFrame {
-    type: 'ObjectBuild';
-    nodes: AstNode[];
-    index: number;
-    result: Obj;
-    currentKey: string | null;
-    isSpread: boolean;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `let` binding — evaluate the value expression, then process destructuring.
- *
- * The trampoline evaluates the value expression. When it completes,
- * `applyFrame` processes `evaluateBindingNodeValues(target, value, ...)`
- * and adds the resulting bindings to the context. The result of the let
- * expression is the evaluated value itself.
- */
-export interface LetBindFrame {
-    type: 'LetBind';
-    target: BindingTarget;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `loop` binding setup — evaluate binding values sequentially.
- *
- * Each binding's value expression is evaluated in a context that includes
- * all previously bound values (bindings can depend on earlier bindings).
- *
- * Phase `'value'`: evaluating a binding's value expression.
- * Phase `'destructure'`: value evaluated, processing destructuring defaults.
- */
-export interface LoopBindFrame {
-    type: 'LoopBind';
-    phase: 'value' | 'destructure';
-    bindingNodes: BindingNode[];
-    index: number;
-    context: Context;
-    body: AstNode;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `loop` body iteration — evaluate body with `recur` handling.
- *
- * In the trampoline, `recur` does NOT throw `RecurSignal`. Instead, when
- * recur args are collected, the trampoline pops back to this frame, rebinds
- * the variables, and re-evaluates the body. This gives proper tail-call
- * elimination without stack growth.
- */
-export interface LoopIterateFrame {
-    type: 'LoopIterate';
-    bindingNodes: BindingNode[];
-    bindingContext: Context;
-    body: AstNode;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * State for a single binding level in a `for`/`doseq` loop.
- *
- * Each level iterates over a `collection`. Inner-level collections are
- * re-evaluated when outer-level bindings change.
- */
-export interface ForBindingLevelState {
-    collection: Arr;
-    index: number;
-}
-/**
- * `for`/`doseq` multi-binding nested iteration.
- *
- * Multi-level nested loop with optional let-bindings, when-guards, and
- * while-guards at each binding level. `for` collects results; `doseq`
- * discards them (side-effects only).
- *
- * Phase describes what sub-expression is currently being evaluated:
- * - `'evalCollection'`: evaluating the collection expression for a level
- * - `'evalElement'`: processing destructuring for the current element
- * - `'evalLet'`: evaluating let-bindings at the current level
- * - `'evalWhen'`: evaluating the when-guard
- * - `'evalWhile'`: evaluating the while-guard
- * - `'evalBody'`: evaluating the loop body
- */
-export interface ForLoopFrame {
-    type: 'ForLoop';
-    returnResult: boolean;
-    bindingNodes: LoopBindingNode[];
-    body: AstNode;
-    result: Arr;
-    phase: 'evalCollection' | 'evalElement' | 'evalLet' | 'evalWhen' | 'evalWhile' | 'evalBody';
-    bindingLevel: number;
-    levelStates: ForBindingLevelState[];
-    context: Context;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `perform` argument collection — evaluate effect ref + args sequentially.
- *
- * First evaluates the effect expression (index 0) to get an EffectRef.
- * Then evaluates each argument expression. When all are collected, produces
- * a `PerformStep` with the resolved EffectRef and argument values.
- */
-export interface PerformArgsFrame {
-    type: 'PerformArgs';
-    argNodes: AstNode[];
-    index: number;
-    params: Arr;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `recur` — evaluate parameters sequentially, then signal tail-call.
- *
- * In the trampoline, instead of throwing `RecurSignal`, the completed
- * recur frame pops the continuation stack to the nearest `LoopIterateFrame`
- * or `FnBodyFrame`, rebinds parameters, and re-enters the loop/body.
- * This eliminates the exception-based control flow used by the recursive
- * evaluator.
- */
-export interface RecurFrame {
-    type: 'Recur';
-    nodes: AstNode[];
-    index: number;
-    params: Arr;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * `do...with` effect handler boundary.
- *
- * Pushed around the do body evaluation. When `perform` is called, the
- * trampoline searches the continuation stack for a matching `TryWithFrame`.
- * The delimited continuation between `perform` and this frame is captured.
- *
- * Handlers are stored as evaluated `[EffectRef, handlerFn AstNode]` pairs.
- * The effect expressions are evaluated eagerly when entering the `try/with`
- * scope (i.e., when the frame is created) via `evaluateNodeRecursive`.
- * This ensures handler matching is deterministic and doesn't depend on
- * state changes inside the do body.
- */
-export interface TryWithFrame {
-    type: 'TryWith';
-    handlers: EvaluatedWithHandler[];
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * A pre-evaluated effect handler pair for `TryWithFrame`.
- * `effectRef` is the resolved EffectRef value.
- * `handlerNode` is the AST node for the handler function expression.
- */
-export interface EvaluatedWithHandler {
-    effectRef: Any;
-    handlerNode: AstNode;
-}
-/**
- * Bridges a handler's return value back to the perform call site.
- *
- * When `perform` matches a `TryWithFrame`, the handler runs with a continuation
- * that excludes the current try/with/catch scope (so errors and effects from
- * the handler propagate upward per P&P semantics). However, the handler's
- * return value needs to resume the body at the perform call site with the
- * TryWithFrame still on the stack (so subsequent performs in the same body
- * can still match handlers).
- *
- * `EffectResumeFrame` is placed below the handler's function frames in the
- * continuation stack. When the handler returns a value, this frame replaces
- * the continuation with `resumeK` — the original continuation from the
- * perform call site, with the TryWithFrame intact.
- *
- * Error/effect semantics:
- * - Handler RETURNS value → EffectResumeFrame redirects to resumeK → body continues
- * - Handler THROWS error → error walks past EffectResumeFrame to outer_k → correct
- * - Handler PERFORMS effect → effect walks past EffectResumeFrame to outer_k → correct
- */
-export interface EffectResumeFrame {
-    type: 'EffectResume';
-    resumeK: ContinuationStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Resume a `parallel(...)` expression after suspension.
- *
- * When a `parallel` has some branches that suspended and some that completed,
- * the continuation is suspended with this frame at the top. On resume, the
- * host provides a value for the first pending suspended branch.
- *
- * `applyFrame` converts this to a `ParallelResumeStep` so that `tick` can
- * handle it with access to `handlers` and `signal`.
- *
- * Fields:
- * - `branchCount`: total number of branches (for ordered result array)
- * - `completedBranches`: branches that already finished `{ index, value }`
- * - `suspendedBranches`: remaining suspended branches `{ index, snapshot }`
- *   The first entry is the one being resumed — its snapshot is NOT used because
- *   the value was already provided by the host. Subsequent entries are pending.
- */
-export interface ParallelResumeFrame {
-    type: 'ParallelResume';
-    branchCount: number;
-    completedBranches: Array<{
-        index: number;
-        value: Any;
-    }>;
-    suspendedBranches: Array<{
-        index: number;
-        snapshot: Snapshot;
-    }>;
-}
-/**
- * Evaluate function call arguments.
- *
- * Evaluates argument expressions sequentially, collecting results into
- * `params`. Handles spread nodes (flatten arrays) and placeholder `_`
- * nodes (record indices for partial application).
- *
- * `fnNode` is the first element of the `NormalExpressionNode` payload —
- * either a symbol node (for named calls) or an expression node (for
- * anonymous calls like `((fn [x] x) 5)`).
- *
- * When all arguments are collected:
- * - Named builtin symbol → dispatch to builtin's evaluate
- * - Named user symbol → look up value, push `CallFnFrame`, dispatch
- * - Anonymous expression → push `CallFnFrame`, evaluate function expression
- */
-export interface EvalArgsFrame {
-    type: 'EvalArgs';
-    node: NormalExpressionNode;
-    index: number;
-    params: Arr;
-    placeholders: number[];
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Dispatch a function call after the function value has been resolved.
- *
- * Pushed when an anonymous function expression needs to be evaluated before
- * calling, or when a compound function type (Comp, Juxt, etc.) needs to
- * chain sub-calls. Receives the resolved function value and dispatches
- * using `executeFunction`.
- */
-export interface CallFnFrame {
-    type: 'CallFn';
-    params: Arr;
-    placeholders: number[];
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * User-defined function body evaluation.
- *
- * After parameter setup (binding destructuring, defaults, rest args), the
- * function body is evaluated as a sequence. This frame also serves as the
- * target for `recur` — when recur params are collected, the trampoline
- * pops to this frame, rebinds parameters, and re-evaluates the body.
- *
- * `fn` is stored for recur handling: the parameter definitions
- * (`fn.evaluatedfunction[0]`) and captured environment
- * (`fn.evaluatedfunction[2]`) are needed to rebind.
- */
-export interface FnBodyFrame {
-    type: 'FnBody';
-    fn: UserDefinedFunction;
-    bodyIndex: number;
-    env: ContextStack;
-    outerEnv: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Evaluate default values during binding destructuring.
- *
- * `evaluateBindingNodeValues` processes destructuring patterns and may need
- * to evaluate default value expressions (e.g., `let [a (= 10) b] [1]` —
- * the default `10` for `b` needs evaluation). This frame captures the
- * state needed to resume destructuring after a default is evaluated.
- *
- * `target` is the overall binding target being destructured.
- * `value` is the value being destructured against the target.
- * `record` accumulates the name→value mappings produced so far.
- */
-export interface BindingDefaultFrame {
-    type: 'BindingDefault';
-    target: BindingTarget;
-    value: Any;
-    record: Record<string, Any>;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * NaN guard after evaluating a normal expression.
- *
- * Normal expressions go through a NaN check: if the result is `NaN`, a
- * `DvalaError` is thrown. This frame wraps that check.
- */
-export interface NanCheckFrame {
-    type: 'NanCheck';
-    sourceCodeInfo?: SourceCodeInfo;
-}
-/**
- * Injected by the trampoline in debug mode (when a `dvala.debug.step` handler
- * is registered). Wraps compound expression evaluation to intercept the result
- * and produce a `PerformStep` for `dvala.debug.step`.
- *
- * Two-phase lifecycle:
- * 1. **awaitValue**: Pushed before evaluating a compound node. Receives the
- *    node's evaluation result, builds step info, and produces a `PerformStep`
- *    for `dvala.debug.step` with the step info as args.
- * 2. **awaitPerform**: The debug perform completed (handler resumed or
- *    suspension was resumed). Passes the value through to the next frame.
- *    For normal stepping, the debugger resumes with the original value.
- *    For `rerunFrom`, the debugger resumes with an alternate value.
- */
-export interface DebugStepFrame {
-    type: 'DebugStep';
-    phase: 'awaitValue' | 'awaitPerform';
-    sourceCodeInfo?: SourceCodeInfo;
-    env: ContextStack;
-}
-/**
- * Discriminated union of all frame types.
- *
- * Each frame captures the continuation state for one recursive call pattern
- * in the evaluator. The `type` field serves as the discriminant.
- *
- * Frame categories:
- * - **Program flow**: SequenceFrame
- * - **Branching**: IfBranchFrame, CondFrame, MatchFrame
- * - **Short-circuit**: AndFrame, OrFrame, QqFrame
- * - **Collection construction**: ArrayBuildFrame, ObjectBuildFrame
- * - **Binding**: LetBindFrame, LoopBindFrame, LoopIterateFrame, ForLoopFrame
- * - **Control flow**: RecurFrame
- * - **Exception & effect handling**: TryWithFrame
- * - **Function calls**: EvalArgsFrame, CallFnFrame, FnBodyFrame
- * - **Destructuring**: BindingDefaultFrame
- * - **Post-processing**: NanCheckFrame
- * - **Debug**: DebugStepFrame
- */
-/**
- * Merges the result of evaluating a module's Dvala source with the module's
- * TypeScript functions. The source must evaluate to an object; its entries
- * are spread over the TS functions map and the combined object is returned
- * as the import result. The merged result is cached in `env` so subsequent
- * imports of the same module reuse the evaluated closures.
- */
-export interface ImportMergeFrame {
-    type: 'ImportMerge';
-    tsFunctions: Obj;
-    moduleName: string;
-    module: DvalaModule;
-    env: ContextStack;
-    sourceCodeInfo?: SourceCodeInfo;
-}
-export type Frame = SequenceFrame | IfBranchFrame | CondFrame | MatchFrame | AndFrame | OrFrame | QqFrame | ArrayBuildFrame | ObjectBuildFrame | LetBindFrame | LoopBindFrame | LoopIterateFrame | ForLoopFrame | RecurFrame | PerformArgsFrame | TryWithFrame | EffectResumeFrame | ParallelResumeFrame | EvalArgsFrame | CallFnFrame | FnBodyFrame | BindingDefaultFrame | NanCheckFrame | DebugStepFrame | ImportMergeFrame;
-/**
- * Array type alias for readability — a continuation stack is just
- * an array of frames. The top of the stack is index 0.
- */
-export type ContinuationStack = Frame[];

package/dist/mcp-server/src/evaluator/interface.d.ts

@@ -1,14 +0,0 @@
-import type { Any, Arr } from '../interface';
-import type { AstNode, FunctionLike } from '../parser/types';
-import type { SourceCodeInfo } from '../tokenizer/token';
-import type { MaybePromise } from '../utils/maybePromise';
-import type { ContextStack } from './ContextStack';
-interface ContextEntry {
-    value: Any;
-}
-export type Context = Record<string, ContextEntry>;
-export type EvaluateNode = (node: AstNode, contextStack: ContextStack) => MaybePromise<Any>;
-export type ExecuteFunction = (fn: FunctionLike, params: Arr, contextStack: ContextStack, sourceCodeInfo?: SourceCodeInfo) => MaybePromise<Any>;
-export type LookUpResult = ContextEntry | null;
-export declare function isContextEntry(value: unknown): value is ContextEntry;
-export {};

package/dist/mcp-server/src/evaluator/standardEffects.d.ts

@@ -1,50 +0,0 @@
-/**
- * Standard effects — built-in effects with default implementations.
- *
- * These effects are always available without requiring explicit host handlers.
- * Host handlers can override them (host handlers take priority in the lookup order).
- *
- * Lookup order: local try/with → host handlers → standard effects → unhandled error
- *
- * Each standard effect has co-located documentation (FunctionDocs) and arity,
- * mirroring the structure of builtin normal expressions and module functions.
- *
- * Sync effects work in both `runSync` and `run`.
- * Async effects (`dvala.sleep`, `dvala.io.read-line` in Node, `dvala.io.read-stdin`) only work in `run` —
- * `runSync` will throw when a Promise surfaces.
- */
-import type { Arity, FunctionDocs } from '../builtin/interface';
-import type { Arr } from '../interface';
-import type { SourceCodeInfo } from '../tokenizer/token';
-import type { ContinuationStack } from './frames';
-import type { Step } from './step';
-/**
- * A standard effect handler returns the next step directly.
- * Sync effects return `Step`, async effects return `Promise<Step>`.
- */
-type StandardEffectHandlerFn = (args: Arr, k: ContinuationStack, sourceCodeInfo?: SourceCodeInfo) => Step | Promise<Step>;
-/**
- * A standard effect definition — mirrors BuiltinNormalExpression structure.
- * Each effect has a handler function, arity for validation, and co-located docs.
- */
-export interface StandardEffectDefinition {
-    handler: StandardEffectHandlerFn;
-    arity: Arity;
-    docs: FunctionDocs;
-}
-/** All standard effect names. */
-export declare const standardEffectNames: ReadonlySet<string>;
-/** All standard effect definitions (for reference data generation). */
-export declare const allStandardEffectDefinitions: Readonly<Record<string, StandardEffectDefinition>>;
-/**
- * Look up a standard effect definition by name.
- * Returns undefined if the effect is not a standard effect.
- */
-export declare function getStandardEffectDefinition(effectName: string): StandardEffectDefinition | undefined;
-/**
- * Look up a standard effect handler by name.
- * Validates arity before calling the handler.
- * Returns undefined if the effect is not a standard effect.
- */
-export declare function getStandardEffectHandler(effectName: string): ((args: Arr, k: ContinuationStack, sourceCodeInfo?: SourceCodeInfo) => Step | Promise<Step>) | undefined;
-export {};