Pixir.VirtualOverlay (pixir v0.1.12)

Copy Markdown View Source

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.

Summary

Functions

classify_read_set_entry(entry, index \\ 0)

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

limit_keys()

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

run(workspace, params, opts \\ [])

Run virtual shell commands over a bounded import from workspace.

validate_read_set(read_set)

Validate the non-empty structural read_set contract for specifications.

validate_read_set_entries(read_set)

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

Functions

classify_read_set_entry(entry, index \\ 0)

@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()

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

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

run(workspace, params, opts \\ [])

@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(read_set)

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

Validate the non-empty structural read_set contract for specifications.

validate_read_set_entries(read_set)

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

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