@mojir/dvala 0.0.1 → 0.0.2

package/dist/cli/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/cli/src/createReadlineInterface.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import type { ReadLine, ReadLineOptions } from 'node:readline';
+type Options = Required<Pick<ReadLineOptions, 'completer' | 'historySize' | 'prompt'>>;
+export declare function createReadlineInterface(options: Options): ReadLine;
+export {};

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