# `PtcRunner.Lisp.Prelude.Compiler`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/lisp/prelude/compiler.ex#L1)

Compiles deployment prelude SOURCE into a `%PtcRunner.Lisp.Prelude{}`
artifact (Capability Prelude V1, plan §1 / §3).

## What this does

  1. Parses the prelude source to raw AST.
  2. Walks the top-level program treating `(ns name "doc" {meta})` as a
     COMPILER-ONLY directive (not a general user-runtime form), and
     `defn`/`defn-` as export/private-helper definitions under the current
     namespace.
  3. Runs compile-time validation that does NOT depend on a selected
     runtime: reserved-namespace rejection, missing/invalid namespace,
     duplicate public refs, invalid visibility, invalid arity/signature
     metadata. Failures are returned as
     `{:error, %PtcRunner.Lisp.Prelude.ValidationError{}}`.
  4. Builds `%Export{}` records for public definitions, normalizing
     kebab-case PTC-Lisp metadata keywords (`:provider-ref`) at the host
     boundary and inferring backing metadata only for literal
     `(tool/call {:server "x" :tool "y" ...})` patterns (plan §3).
  5. Captures a callable private prelude env by analyzing+evaluating the
     definition forms (ns directives stripped, `defn-` rewritten to `defn`)
     through the existing PTC-Lisp pipeline. The captured value is the
     resulting `user_ns` map (bare symbol => `{:closure, ...}`). NOTE: the
     evaluator's lexical closure capture does NOT fold sibling top-level
     defs into each closure's `captured_env` — sibling helpers resolve by
     name through `user_ns` at CALL time. The whole `private_env` map IS
     that namespace, so P2 must thread `private_env` as the user_ns layer
     when invoking an export for siblings to resolve (fact #6 capture seam,
     proven end-to-end during P0).
  6. Computes a sha256 source hash (plan §12).

Attach-time `requires` validation against a selected upstream runtime is a
SEPARATE later phase and is not performed here.

# `compile`

```elixir
@spec compile(String.t()) ::
  {:ok, PtcRunner.Lisp.Prelude.t()}
  | {:error, PtcRunner.Lisp.Prelude.ValidationError.t()}
```

Compiles prelude `source` into a `%PtcRunner.Lisp.Prelude{}`.

Returns `{:ok, prelude}` or `{:error, %ValidationError{}}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*