yukigo 0.1.0

package/dist/interpreter/components/PatternMatcher.js

@@ -0,0 +1,206 @@
+import { ConstructorPattern, isLazyList, ListPrimitive, } from "@yukigo/ast";
+import { InterpreterVisitor } from "./Visitor.js";
+import { createStream } from "../utils.js";
+export class PatternResolver {
+    visitVariablePattern(node) {
+        return node.name.value;
+    }
+    visitWildcardPattern(node) {
+        return "_";
+    }
+    visitLiteralPattern(node) {
+        const { name } = node;
+        if (name instanceof ListPrimitive)
+            return String(name.elements.map((elem) => elem.accept(this)));
+        return String(name.value);
+    }
+    visitTuplePattern(node) {
+        return String(node.elements.map((elem) => elem.accept(this)));
+    }
+    visitListPattern(node) {
+        const { elements } = node;
+        return elements.length === 0
+            ? "[]"
+            : String(elements.map((elem) => elem.accept(this)));
+    }
+    visitConsPattern(node) {
+        const head = node.head.accept(this);
+        const tail = node.tail.accept(this);
+        return `(${head}:${tail})`;
+    }
+    visitConstructorPattern(node) {
+        const constr = node.constr;
+        const args = node.patterns.map((pat) => pat.accept(this)).join(" ");
+        return `${constr} ${args}`;
+    }
+    visitFunctorPattern(node) {
+        // Same as ConstructorPattern (alias)
+        return this.visitConstructorPattern(new ConstructorPattern(node.identifier.value, node.args));
+    }
+    visitApplicationPattern(node) {
+        // Same as FunctorPattern
+        return this.visitConstructorPattern(new ConstructorPattern(node.symbol.value, node.args));
+    }
+    visitAsPattern(node) {
+        const pattern = node.pattern.accept(this);
+        const alias = node.alias.accept(this);
+        return `${alias}@${pattern}`;
+    }
+    visit(node) {
+        return node.accept(this);
+    }
+}
+/**
+ * Recursively matches a value against a pattern node.
+ * Updates `bindings` when variables are bound successfully.
+ * Returns true if the pattern matches, false otherwise.
+ */
+export class PatternMatcher {
+    value;
+    bindings;
+    constructor(value, bindings) {
+        this.value = value;
+        this.bindings = bindings;
+    }
+    visitVariablePattern(node) {
+        this.bindings.push([node.name.value, this.value]);
+        return true;
+    }
+    visitWildcardPattern(node) {
+        return true;
+    }
+    visitLiteralPattern(node) {
+        const literalValue = InterpreterVisitor.evaluateLiteral(node.name);
+        return this.deepEqual(this.value, literalValue);
+    }
+    visitTuplePattern(node) {
+        if (!Array.isArray(this.value))
+            return false;
+        if (this.value.length !== node.elements.length)
+            return false;
+        for (let i = 0; i < node.elements.length; i++) {
+            const matcher = new PatternMatcher(this.value[i], this.bindings);
+            if (!node.elements[i].accept(matcher))
+                return false;
+        }
+        return true;
+    }
+    visitListPattern(node) {
+        // empty list case
+        if (node.elements.length === 0) {
+            if (Array.isArray(this.value))
+                return this.value.length === 0;
+            if (isLazyList(this.value)) {
+                const iter = this.value.generator();
+                return iter.next().done;
+            }
+            return false;
+        }
+        // finite list case
+        if (Array.isArray(this.value))
+            return this.matchList(node.elements, this.value);
+        // lazy list case
+        if (isLazyList(this.value)) {
+            const realized = this.realize(this.value);
+            return this.matchList(node.elements, realized);
+        }
+        return false;
+    }
+    matchList(elements, value) {
+        if (value.length !== elements.length)
+            return false;
+        for (let i = 0; i < elements.length; i++) {
+            const matcher = new PatternMatcher(value[i], this.bindings);
+            const isMatch = elements[i].accept(matcher);
+            if (!isMatch)
+                return false;
+        }
+        return true;
+    }
+    visitConsPattern(node) {
+        const [head, tail] = this.resolveCons(this.value);
+        if (!head || !tail)
+            return false;
+        const headMatcher = new PatternMatcher(head, this.bindings);
+        const headMatches = node.head.accept(headMatcher);
+        if (!headMatches)
+            return false;
+        const tailMatcher = new PatternMatcher(tail, this.bindings);
+        return node.tail.accept(tailMatcher);
+    }
+    resolveCons(list) {
+        if (Array.isArray(list))
+            return list.length === 0 ? [null, null] : [list[0], list.slice(1)];
+        if (isLazyList(list)) {
+            const headIter = list.generator();
+            const next = headIter.next();
+            if (next.done)
+                return [null, null];
+            const parentGeneratorFactory = list.generator;
+            const tailGenerator = function* () {
+                const freshIter = parentGeneratorFactory();
+                freshIter.next();
+                let next;
+                while (!(next = freshIter.next()).done)
+                    yield next.value;
+            };
+            return [next.value, createStream(tailGenerator)];
+        }
+        return [null, null];
+    }
+    visitConstructorPattern(node) {
+        if (!Array.isArray(this.value) || this.value.length === 0)
+            return false;
+        if (this.value[0] !== node.constr)
+            return false;
+        const args = this.value.slice(1);
+        return this.matchList(node.patterns, args);
+    }
+    visitFunctorPattern(node) {
+        return this.visitConstructorPattern(new ConstructorPattern(node.identifier.value, node.args));
+    }
+    visitApplicationPattern(node) {
+        return this.visitConstructorPattern(new ConstructorPattern(node.symbol.value, node.args));
+    }
+    visitAsPattern(node) {
+        const innerMatcher = new PatternMatcher(this.value, this.bindings);
+        const innerMatches = node.pattern.accept(innerMatcher);
+        if (!innerMatches)
+            return false;
+        const aliasMatcher = new PatternMatcher(this.value, this.bindings);
+        return node.alias.accept(aliasMatcher);
+    }
+    visitUnionPattern(node) {
+        for (const pattern of node.patterns) {
+            const trialBindings = [];
+            const matcher = new PatternMatcher(this.value, trialBindings);
+            if (pattern.accept(matcher)) {
+                this.bindings.push(...trialBindings);
+                return true;
+            }
+        }
+        return false;
+    }
+    visit(node) {
+        return node.accept(this);
+    }
+    deepEqual(a, b) {
+        if (a === b)
+            return true;
+        if (typeof a !== typeof b)
+            return false;
+        if (Array.isArray(a) && Array.isArray(b)) {
+            if (a.length !== b.length)
+                return false;
+            for (let i = 0; i < a.length; i++) {
+                if (!this.deepEqual(a[i], b[i]))
+                    return false;
+            }
+            return true;
+        }
+        return false;
+    }
+    realize(value) {
+        return new InterpreterVisitor([new Map()], {}).realizeList(value);
+    }
+}

package/dist/interpreter/components/Visitor.d.ts

@@ -0,0 +1,64 @@
+import { Visitor, PrimitiveValue, NumberPrimitive, BooleanPrimitive, StringPrimitive, ListPrimitive, NilPrimitive, SymbolPrimitive, Variable, CharPrimitive, ArithmeticUnaryOperation, ArithmeticBinaryOperation, ListUnaryOperation, ListBinaryOperation, ComparisonOperation, LogicalBinaryOperation, LogicalUnaryOperation, BitwiseBinaryOperation, BitwiseUnaryOperation, StringOperation, UnifyOperation, AssignOperation, TupleExpression, FieldExpression, DataExpression, ConsExpression, LetInExpression, Call, Otherwise, CompositionExpression, Expression, Application, Lambda, Exist, Not, Findall, Forall, Goal, Send, New, Implement, Include, Self, ListComprehension, RangeExpression, Generator as YuGenerator, ASTNode, Raise, Query } from "@yukigo/ast";
+import { EnvStack, InterpreterConfig } from "../index.js";
+import { ExpressionEvaluator } from "../utils.js";
+import { ErrorFrame } from "../errors.js";
+export declare class InterpreterVisitor implements Visitor<PrimitiveValue>, ExpressionEvaluator {
+    private frames;
+    private env;
+    private readonly config;
+    constructor(env: EnvStack, config: InterpreterConfig, frames?: ErrorFrame[]);
+    evaluate(node: Expression): PrimitiveValue;
+    private getLogicEngine;
+    visitNumberPrimitive(node: NumberPrimitive): PrimitiveValue;
+    visitBooleanPrimitive(node: BooleanPrimitive): PrimitiveValue;
+    visitStringPrimitive(node: StringPrimitive): PrimitiveValue;
+    visitListPrimitive(node: ListPrimitive): PrimitiveValue;
+    visitNilPrimitive(node: NilPrimitive): PrimitiveValue;
+    visitCharPrimitive(node: CharPrimitive): PrimitiveValue;
+    visitSymbolPrimitive(node: SymbolPrimitive): PrimitiveValue;
+    visitVariable(node: Variable): PrimitiveValue;
+    visitArithmeticUnaryOperation(node: ArithmeticUnaryOperation): PrimitiveValue;
+    visitArithmeticBinaryOperation(node: ArithmeticBinaryOperation): PrimitiveValue;
+    visitListUnaryOperation(node: ListUnaryOperation): PrimitiveValue;
+    visitListBinaryOperation(node: ListBinaryOperation): PrimitiveValue;
+    visitComparisonOperation(node: ComparisonOperation): PrimitiveValue;
+    visitLogicalBinaryOperation(node: LogicalBinaryOperation): PrimitiveValue;
+    visitLogicalUnaryOperation(node: LogicalUnaryOperation): PrimitiveValue;
+    visitBitwiseBinaryOperation(node: BitwiseBinaryOperation): PrimitiveValue;
+    visitBitwiseUnaryOperation(node: BitwiseUnaryOperation): PrimitiveValue;
+    visitStringOperation(node: StringOperation): PrimitiveValue;
+    visitUnifyOperation(node: UnifyOperation): PrimitiveValue;
+    visitAssignOperation(node: AssignOperation): PrimitiveValue;
+    visitTupleExpr(node: TupleExpression): PrimitiveValue;
+    visitFieldExpr(node: FieldExpression): PrimitiveValue;
+    visitDataExpr(node: DataExpression): PrimitiveValue;
+    visitConsExpr(node: ConsExpression): PrimitiveValue;
+    visitLetInExpr(node: LetInExpression): PrimitiveValue;
+    visitCall(node: Call): PrimitiveValue;
+    visitOtherwise(node: Otherwise): PrimitiveValue;
+    visitCompositionExpression(node: CompositionExpression): PrimitiveValue;
+    visitLambda(node: Lambda): PrimitiveValue;
+    visitApplication(node: Application): PrimitiveValue;
+    visitQuery(node: Query): PrimitiveValue;
+    visitExist(node: Exist): PrimitiveValue;
+    visitNot(node: Not): PrimitiveValue;
+    visitFindall(node: Findall): PrimitiveValue;
+    visitForall(node: Forall): PrimitiveValue;
+    visitGoal(node: Goal): PrimitiveValue;
+    visitSend(node: Send): PrimitiveValue;
+    visitNew(node: New): PrimitiveValue;
+    visitImplement(node: Implement): PrimitiveValue;
+    visitInclude(node: Include): PrimitiveValue;
+    visitSelf(node: Self): PrimitiveValue;
+    visitListComprehension(node: ListComprehension): PrimitiveValue;
+    visitGenerator(node: YuGenerator): PrimitiveValue;
+    visitRaise(node: Raise): PrimitiveValue;
+    visitRangeExpression(node: RangeExpression): PrimitiveValue;
+    visit(node: Expression): PrimitiveValue;
+    private safelyVisit;
+    private isRuntimeFunction;
+    realizeList(val: PrimitiveValue): PrimitiveValue[];
+    private processBinary;
+    private processUnary;
+    static evaluateLiteral(node: ASTNode): PrimitiveValue;
+}

package/dist/interpreter/components/Visitor.js

@@ -0,0 +1,299 @@
+import { SymbolPrimitive, VariablePattern, Application, Lambda, UnguardedBody, Sequence, Return, } from "@yukigo/ast";
+import { ArithmeticBinaryTable, ArithmeticUnaryTable, BitwiseBinaryTable, BitwiseUnaryTable, ComparisonOperationTable, ListBinaryTable, ListUnaryTable, LogicalBinaryTable, LogicalUnaryTable, StringOperationTable, } from "./Operations.js";
+import { define, lookup } from "../utils.js";
+import { LogicEngine } from "./LogicEngine.js";
+import { InterpreterError, UnexpectedValue } from "../errors.js";
+import { LazyRuntime } from "./LazyRuntime.js";
+import { FunctionRuntime } from "./FunctionRuntime.js";
+export class InterpreterVisitor {
+    frames;
+    env;
+    config;
+    constructor(env, config, frames = []) {
+        this.frames = frames;
+        this.env = env;
+        this.config = config;
+    }
+    evaluate(node) {
+        return node.accept(this);
+    }
+    getLogicEngine() {
+        return new LogicEngine(this.env, this.config, this);
+    }
+    visitNumberPrimitive(node) {
+        return node.value;
+    }
+    visitBooleanPrimitive(node) {
+        return node.value;
+    }
+    visitStringPrimitive(node) {
+        return node.value;
+    }
+    visitListPrimitive(node) {
+        return node.elements.map((elem) => elem.accept(this));
+    }
+    visitNilPrimitive(node) {
+        return node.value;
+    }
+    visitCharPrimitive(node) {
+        return node.value;
+    }
+    visitSymbolPrimitive(node) {
+        try {
+            return lookup(this.env, node.value);
+        }
+        catch (error) {
+            throw new InterpreterError("Symbol Lookup", error.message, this.frames);
+        }
+    }
+    visitVariable(node) {
+        const name = node.identifier.value;
+        const value = node.expression.accept(this);
+        this.env.at(-1).set(name, value);
+        return true;
+    }
+    visitArithmeticUnaryOperation(node) {
+        return this.processUnary(node, ArithmeticUnaryTable, (a) => !Number.isNaN(a), "ArithmeticUnaryOperation");
+    }
+    visitArithmeticBinaryOperation(node) {
+        return this.processBinary(node, ArithmeticBinaryTable, (a, b) => typeof a === "number" && typeof b === "number", "ArithmeticBinaryOperation");
+    }
+    visitListUnaryOperation(node) {
+        const operand = node.operand.accept(this);
+        if (!Array.isArray(operand))
+            throw new UnexpectedValue("ListUnaryOperation", "Array", typeof operand);
+        const arr = this.realizeList(operand);
+        const fn = ListUnaryTable[node.operator];
+        if (!fn)
+            throw new InterpreterError("ListUnaryOperation", `Unknown operator: ${node.operator}`);
+        return fn(arr);
+    }
+    visitListBinaryOperation(node) {
+        return this.processBinary(node, ListBinaryTable, (a, b) => Array.isArray(a) && Array.isArray(b), "ListBinaryOperation");
+    }
+    visitComparisonOperation(node) {
+        return this.processBinary(node, ComparisonOperationTable, () => true, "ComparisonOperation");
+    }
+    visitLogicalBinaryOperation(node) {
+        const left = node.left.accept(this);
+        if (typeof left !== "boolean")
+            throw new InterpreterError("LogicalBinaryOperation", `Expected left side to be boolean and got: ${left}`);
+        const fn = LogicalBinaryTable[node.operator];
+        if (!fn)
+            throw new InterpreterError("LogicalBinaryOperation", `Unknown operator '${node.operator}'`);
+        const rightThunk = () => {
+            const right = node.right.accept(this);
+            if (typeof right !== "boolean")
+                throw new InterpreterError("LogicalBinaryOperation", `Expected right side to be boolean and got: ${right}`);
+            return right;
+        };
+        // short circuit if lazy loading is enabled
+        if (this.config.lazyLoading) {
+            if (node.operator === "And" && left === false)
+                return false;
+            if (node.operator === "Or" && left === true)
+                return true;
+        }
+        return fn(left, rightThunk);
+    }
+    visitLogicalUnaryOperation(node) {
+        return this.processUnary(node, LogicalUnaryTable, (a) => typeof a === "boolean", "LogicalUnaryOperation");
+    }
+    visitBitwiseBinaryOperation(node) {
+        return this.processBinary(node, BitwiseBinaryTable, (a, b) => !Number.isNaN(a) && !Number.isNaN(b), "BitwiseBinaryOperation");
+    }
+    visitBitwiseUnaryOperation(node) {
+        return this.processUnary(node, BitwiseUnaryTable, (a) => !Number.isNaN(a), "BitwiseUnaryOperation");
+    }
+    visitStringOperation(node) {
+        return this.processBinary(node, StringOperationTable, (a, b) => typeof a === "string" || typeof b === "string", "StringOperation");
+    }
+    visitUnifyOperation(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitAssignOperation(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitTupleExpr(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitFieldExpr(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitDataExpr(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitConsExpr(node) {
+        try {
+            return LazyRuntime.evaluateCons(node, this, this.config.lazyLoading);
+        }
+        catch (e) {
+            throw new InterpreterError("Cons", e.message, this.frames);
+        }
+    }
+    visitLetInExpr(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitCall(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitOtherwise(node) {
+        return true;
+    }
+    visitCompositionExpression(node) {
+        const f = node.left.accept(this);
+        const g = node.right.accept(this);
+        if (!this.isRuntimeFunction(f) || !this.isRuntimeFunction(g))
+            throw new InterpreterError("CompositionExpression", "Both operands of (.) must be functions");
+        const fName = `__comp_f_${Date.now()}_${Math.random()
+            .toString(36)
+            .substring(2, 5)}`;
+        const gName = `__comp_g_${Date.now()}_${Math.random()
+            .toString(36)
+            .substring(2, 5)}`;
+        define(this.env, fName, f);
+        define(this.env, gName, g);
+        const arity = g.arity;
+        const placeholders = Array.from({ length: arity }, (_, i) => new VariablePattern(new SymbolPrimitive(`_p${i}`)));
+        const gCall = placeholders.reduce((acc, p) => new Application(acc, new SymbolPrimitive(p.name.value)), new SymbolPrimitive(gName));
+        const composedBody = new Application(new SymbolPrimitive(fName), gCall);
+        const lambda = new Lambda(placeholders, composedBody);
+        return lambda.accept(this);
+    }
+    visitLambda(node) {
+        const patterns = node.parameters;
+        const equation = {
+            patterns,
+            body: new UnguardedBody(new Sequence([new Return(node.body)])),
+        };
+        return {
+            arity: patterns.length,
+            equations: [equation],
+            pendingArgs: [],
+            identifier: "<lambda>",
+            closure: Array.from(this.env),
+        };
+    }
+    visitApplication(node) {
+        const func = node.functionExpr.accept(this);
+        if (!this.isRuntimeFunction(func))
+            throw new InterpreterError("Application", "Cannot apply non-function");
+        const argThunk = () => node.parameter.accept(this);
+        const pending = func.pendingArgs
+            ? [...func.pendingArgs, argThunk]
+            : [argThunk];
+        // partially applied
+        if (pending.length < func.arity)
+            return {
+                ...func,
+                pendingArgs: pending,
+            };
+        //  fully applied
+        if (pending.length === func.arity) {
+            const evaluatedArgs = pending.map((arg) => typeof arg === "function" ? arg() : arg);
+            const executionEnv = func.closure ?? this.env;
+            return FunctionRuntime.apply(func.identifier ?? "<anonymous>", func.equations, evaluatedArgs, executionEnv, (newEnv) => new InterpreterVisitor(newEnv, this.config, this.frames));
+        }
+        throw new InterpreterError("Application", "Too many arguments provided");
+    }
+    visitQuery(node) {
+        return this.getLogicEngine().solveQuery(node);
+    }
+    visitExist(node) {
+        return this.getLogicEngine().solveExist(node);
+    }
+    visitNot(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitFindall(node) {
+        return this.getLogicEngine().solveFindall(node);
+    }
+    visitForall(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitGoal(node) {
+        return this.getLogicEngine().solveGoal(node);
+    }
+    visitSend(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitNew(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitImplement(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitInclude(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitSelf(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitListComprehension(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitGenerator(node) {
+        throw new Error("Method not implemented.");
+    }
+    visitRaise(node) {
+        const msg = node.body.accept(this);
+        if (typeof msg !== "string")
+            throw new UnexpectedValue("Raise", "string", typeof msg);
+        throw new InterpreterError("Raise", msg);
+    }
+    visitRangeExpression(node) {
+        try {
+            return LazyRuntime.evaluateRange(node, this, this.config);
+        }
+        catch (e) {
+            throw new InterpreterError("Range", e.message, this.frames);
+        }
+    }
+    visit(node) {
+        return this.safelyVisit(node, () => node.accept(this));
+    }
+    safelyVisit(node, fn) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (err instanceof InterpreterError) {
+                err.pushFrame({ nodeType: node.constructor.name, loc: node.loc });
+                throw err;
+            }
+            const wrapped = new InterpreterError(node.constructor.name, err.message, [...this.frames, { nodeType: node.constructor.name, loc: node.loc }]);
+            throw wrapped;
+        }
+    }
+    isRuntimeFunction(val) {
+        return (typeof val === "object" &&
+            val !== null &&
+            Array.isArray(val.equations) &&
+            typeof val.arity === "number");
+    }
+    realizeList(val) {
+        return LazyRuntime.realizeList(val);
+    }
+    processBinary(node, table, typeGuard, contextName) {
+        const left = node.left.accept(this);
+        const right = node.right.accept(this);
+        if (!typeGuard(left, right))
+            throw new InterpreterError(contextName, `Type mismatch: ${left}, ${right}`, this.frames);
+        const fn = table[node.operator];
+        if (!fn)
+            throw new InterpreterError(contextName, `Unknown op: ${node.operator}`);
+        return fn(left, right);
+    }
+    processUnary(node, table, typeGuard, contextName) {
+        const operand = node.operand.accept(this);
+        if (!typeGuard(operand))
+            throw new InterpreterError(contextName, `Type mismatch: ${operand}`, this.frames);
+        const fn = table[node.operator];
+        if (!fn)
+            throw new InterpreterError(contextName, `Unknown op: ${node.operator}`);
+        return fn(operand);
+    }
+    static evaluateLiteral(node) {
+        return node.accept(new InterpreterVisitor([new Map()], { lazyLoading: false }));
+    }
+}

package/dist/interpreter/errors.d.ts

@@ -0,0 +1,19 @@
+import { SourceLocation } from "@yukigo/ast";
+export interface ErrorFrame {
+    nodeType: string;
+    loc?: SourceLocation;
+}
+export declare class InterpreterError extends Error {
+    context: string;
+    frames: ErrorFrame[];
+    constructor(context: string, message: string, frames?: ErrorFrame[]);
+    pushFrame(frame: ErrorFrame): void;
+    formatStack(): string;
+    toString(): string;
+}
+export declare class UnexpectedValue extends InterpreterError {
+    constructor(ctx: string, expected: string, got: string);
+}
+export declare class UnboundVariable extends Error {
+    constructor(name: string);
+}

package/dist/interpreter/errors.js

@@ -0,0 +1,36 @@
+export class InterpreterError extends Error {
+    context;
+    frames;
+    constructor(context, message, frames = []) {
+        super(`[${context}] ${message}`);
+        this.context = context;
+        this.frames = frames;
+    }
+    pushFrame(frame) {
+        this.frames.push(frame);
+    }
+    formatStack() {
+        if (!this.frames.length)
+            return "";
+        const formatted = this.frames
+            .map((f) => {
+            const loc = f.loc ? ` (line ${f.loc.line}, col ${f.loc.column})` : "";
+            return `  • ${f.nodeType}${loc}`;
+        })
+            .join("\n");
+        return `\nTrace:\n${formatted}`;
+    }
+    toString() {
+        return `${this.message}${this.formatStack()}`;
+    }
+}
+export class UnexpectedValue extends InterpreterError {
+    constructor(ctx, expected, got) {
+        super(ctx, `Expected ${expected} but got ${got}`);
+    }
+}
+export class UnboundVariable extends Error {
+    constructor(name) {
+        super(`Unbound variable: ${name}`);
+    }
+}

package/dist/interpreter/index.d.ts

@@ -0,0 +1,32 @@
+import { PrimitiveValue, Expression, AST } from "@yukigo/ast";
+export type Bindings = [string, PrimitiveValue][];
+export type LogicSearchMode = "first" | "all" | "stream";
+export type InterpreterConfig = {
+    lazyLoading?: boolean;
+    debug?: boolean;
+    outputMode?: LogicSearchMode;
+};
+export type Environment = Map<string, PrimitiveValue>;
+export type EnvStack = Environment[];
+/**
+ * The Interpreter class is responsible for evaluating the Abstract Syntax Tree (AST)
+ * generated by the parsers.
+ *
+ * It manages the global execution environment and delegates the actual evaluation
+ * of Expression nodes to a dedicated visitor.
+ */
+export declare class Interpreter {
+    private globalEnv;
+    private readonly config;
+    /**
+     * @param ast The Abstract Syntax Tree (AST) of the program to be interpreted.
+     */
+    constructor(ast: AST, config?: InterpreterConfig);
+    /**
+     * Evaluates a single Expression node within the context of the global environment.
+     *
+     * @param expr The root Expression node to be evaluated.
+     * @returns The resulting primitive value (number, string, boolean, etc.) after evaluation.
+     */
+    evaluate(expr: Expression): PrimitiveValue;
+}