> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lionlang.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# run() — evaluate a Lion expression

> The primary entry point for executing Lion programs. Decodes, evaluates, and provisions the environment, returning a fully self-contained typed Effect.

`run` is the primary entry point for executing Lion programs. It accepts any JSON-compatible value as the expression and a plain object as the evaluation environment, then takes care of schema decoding, evaluation dispatch, and Effect context provisioning so callers do not need to interact with the internals directly.

## Signature

```typescript theme={null}
import { run } from "@lionlang/core/evaluation/evaluate";

export const run = (
  expression: unknown,
  environment: Record<string, unknown>
) => Effect.Effect<unknown, ParseError | ArgumentMismatchError | InvalidFunctionCallError, never>
```

## Parameters

<ParamField path="expression" type="unknown" required>
  The Lion expression to evaluate. Accepts any JSON-compatible value — a JSON
  primitive (`string`, `number`, `boolean`, `null`), an array of Lion
  expressions, or a record with string keys and Lion expression values. The
  value is decoded against `LionExpressionSchema` before evaluation begins.
</ParamField>

<ParamField path="environment" type="Record<string, unknown>" required>
  Name bindings available during evaluation. Keys are identifier strings;
  values can be primitives, objects, or JavaScript functions. Pass the
  `stdlib` export from `@lionlang/core/modules` to make the standard library
  available, then spread in any additional host bindings.
</ParamField>

## Return value

<ResponseField name="Effect" type="Effect.Effect<unknown, ParseError | ArgumentMismatchError | InvalidFunctionCallError, never>">
  An Effect that, when run, yields the evaluated result or fails with one of three typed errors:

  <Expandable title="errors">
    <ResponseField name="ParseError" type="effect/ParseResult">
      Raised when `expression` does not conform to `LionExpressionSchema` — for
      example when a record key is empty or contains `__proto__`.
    </ResponseField>

    <ResponseField name="ArgumentMismatchError" type="ArgumentMismatchError">
      Raised when a stdlib function receives arguments of the wrong type.
    </ResponseField>

    <ResponseField name="InvalidFunctionCallError" type="InvalidFunctionCallError">
      Raised when the head of an array expression does not resolve to a callable.
    </ResponseField>
  </Expandable>
</ResponseField>

## Pipeline

Internally, `run` composes three steps:

1. **Schema decoding** — `Schema.decodeUnknown(LionExpressionSchema)` validates and narrows `expression` to `LionExpressionType`.
2. **Evaluation** — the decoded expression is passed to `evaluate`, which dispatches to the appropriate handler.
3. **Environment provision** — `LionEnvironmentService` is provided via `Effect.provideServiceEffect`, wrapping `environment` in a mutable `Ref`-backed store so `define` can update bindings at runtime.

## Example

```typescript theme={null}
import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

// Simple arithmetic
const result = await Effect.runPromise(
  run(["number/add", 1, 2], stdlib)
);
// => 3

// Custom environment bindings
const env = {
  ...stdlib,
  price: 100,
  taxRate: 0.08,
};

const total = await Effect.runPromise(
  run(
    ["number/add", "price", ["number/multiply", "price", "taxRate"]],
    env
  )
);
// => 108
```

<Note>
  `run` provisions `LionEnvironmentService` internally, so the returned Effect
  has no remaining requirements (`never`). You can pass it directly to
  `Effect.runPromise`, `Effect.runSync`, or any other Effect runner without
  additional setup.
</Note>