# `Pixir.VirtualOverlay`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/virtual_overlay.ex#L1)

BEAM-native virtual workspace runner for future `virtual_overlay` Subagent work.

The runner imports an explicit, bounded read set from a real Pixir Workspace into a
Bashex in-memory filesystem, executes virtual shell commands there, and returns an
ADR 0029 `virtual_diff` artifact. It is deliberately not a model-visible Tool and it
does not apply virtual writes back to the parent Workspace.

One shared classifier rejects absolute paths, lexical parent components, invalid
entries, and normalized whole-Workspace recursive catch-alls before import. Bounded
directory or extension patterns remain valid and all existing file, byte, and
post-expansion symlink limits still apply.

# `classify_read_set_entry`

```elixir
@spec classify_read_set_entry(term(), non_neg_integer()) :: :ok | {:error, map()}
```

Classify one read-set entry without rendering a caller-specific error envelope.

The returned zero-based `index` and stable `reason` are shared by Workflow, Delegate,
Subagent Manager, Tool, and engine boundaries. Classification is lexical: absolute
paths and every `..` component are rejected before normalization; empty/dot components
are then removed and adjacent `**` components collapsed to detect whole-Workspace
recursive aliases.

# `limit_keys`

```elixir
@spec limit_keys() :: [String.t()]
```

The accepted limit keys, as strings — the single source for spec validators.

# `run`

```elixir
@spec run(String.t(), map(), keyword()) :: {:ok, map()} | {:error, map()}
```

Run virtual shell commands over a bounded import from `workspace`.

Parameters are string-keyed for parity with Tool and Workflow inputs:

- `"read_set"`: explicit files or bounded glob patterns to import.
- `"commands"`: virtual shell commands to execute in order.
- `"limits"`: optional numeric overrides for the built-in default limits.

# `validate_read_set`

```elixir
@spec validate_read_set(term()) :: :ok | {:error, atom() | map()}
```

Validate the non-empty structural read_set contract for specifications.

# `validate_read_set_entries`

```elixir
@spec validate_read_set_entries(term()) :: :ok | {:error, atom() | map()}
```

Validate supplied entries while allowing the engine's intentional empty scratch import.

---

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