# Embedding API

Decodal core can be embedded without giving the core crate access to a filesystem.
The host supplies imports through `ImportLoader` and may also provide global bindings through the host prelude API.

## Host prelude

`Engine` owns a prelude environment.
Bindings in this environment are visible from every module loaded by the engine.

```text
prelude env
  ↓
module root env
  ↓
let / function env
```

Module top-level bindings shadow prelude bindings.
Primitive type names such as `String`, `Int`, `Float`, and `Bool` are handled before environment lookup, so they are reserved and cannot be shadowed by host bindings.

## Global bindings

The host can bind values before adding or evaluating user sources.

```rust
use decodal::{EmptyLoader, Engine, HostValue};

let mut engine = Engine::new(EmptyLoader);

engine.bind_global(
    "Service",
    HostValue::object([
        ("name", HostValue::string_type()),
        ("port", HostValue::int_type().gt(443).default_int(8443)?),
        ("enabled", HostValue::bool_type().default_bool(true)?),
    ]),
)?;
```

A user source can then refer to `Service` without importing it.

```dcdl
Service & {
  name = "api";
  port = 9443;
}
```

## HostValue

`HostValue` is the public builder-facing value representation for embedding.
It keeps host code from constructing internal `ThunkId` or `ObjectValue` values directly.

```text
HostValue =
  String
  Int
  Float
  Bool
  Array(Vec<HostValue>)
  ArrayConstraint { item, constraints, default }
  Object(Vec<HostField>)
  Abstract { constraints, default }
```

When a host value is bound, the engine internalizes it into `RuntimeValue` and allocates value thunks for object fields, array items, and defaults.

`HostValue::array_of(item)` builds an array constraint with a required element schema.
There is no host API for an unconstrained abstract array.

## Abstract host objects

A host-provided schema object is represented as a concrete object structure whose fields may contain abstract values.

```rust
HostValue::object([
    ("name", HostValue::string_type()),
    ("port", HostValue::int_type().gt(443).default_int(8443)?),
])
```

Conceptually this becomes:

```text
Concrete(Object {
  name -> Thunk(Abstract { constraints: [String], default: none })
  port -> Thunk(Abstract { constraints: [Int, > 443], default: 8443 })
})
```

This matches the runtime model used for Decodal source-defined schema objects.

## Typed Rust integration

Hosts can enable the `derive` feature on `decodal` to keep a Rust struct, the Decodal schema, and the decoded result in sync.
The derive implements two traits from the `decodal` crate:

- `DecodalSchema`: builds a `HostValue` schema that can be passed to `Engine::bind_global`.
- `DecodalDecode`: decodes materialized `Data` back into the Rust type.

```rust
use decodal::{Decodal, DecodalDecode, DecodalSchema, EmptyLoader, Engine};

#[derive(Decodal)]
struct Service {
    name: String,

    #[decodal(gt = 443, default = 8443)]
    port: i64,

    #[decodal(rename = "feature.enable", default = true)]
    feature_enabled: bool,
}

let mut engine = Engine::new(EmptyLoader);
engine.bind_global("Service", Service::decodal_schema())?;

let value = engine.eval_module(module)?;
let data = engine.materialize(&value)?;
let service = Service::decodal_decode(&data)?;
```

Supported field attributes are intentionally small:

- `rename = "path.to.field"`
- `default`
- `default = value`
- numeric constraints: `gt`, `gte`, `lt`, `lte`

The derive does not add host callbacks or reflection.
It only generates schema construction and typed decoding code.

## ImportLoader and prelude together

`ImportLoader` and host prelude bindings are independent mechanisms.

- Use `ImportLoader` when user sources should explicitly import host-provided sources or values.
- Use prelude bindings when host-provided schemas or constants should be globally available.

Both mechanisms share the same runtime evaluator, thunk model, and materialization rules.

## Structured imports

`ImportLoader::load` returns either `LoadedImport::Source` or `LoadedImport::Value`.
The value variant carries a `HostValue`, allowing a host to parse non-Decodal resources such as Markdown into an application-specific structure.

```text
import "./post.md"
  -> host parses content
  -> LoadedImport::Value(
       { frontmatter: {...}, body: "..." }
     )
  -> Engine internalizes HostValue
  -> normal composition and materialization
```

The core does not select content types or bundle Markdown/frontmatter parsers.
The loader owns path resolution, media or extension dispatch, parsing rules, and parse diagnostics.
The stable loader key is also used to cache structured imports.

When a structured value fails a Decodal constraint, the diagnostic keeps the Decodal constraint span and identifies the host value by its stable import key and logical value path, such as `content/post.md` and `frontmatter.draft`.
`HostValue` does not need source spans: syntax diagnostics for the external format remain the loader's responsibility, while cross-value validation reports semantic provenance.

`load` is the single import hook: loaders dispatch by extension, media type, or another host-defined rule and return the appropriate variant directly.