# Class LittleGhost::Workspace

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Workspace.html

A Workspace names the host paths associated with a Run. Pair it with a Sandbox
to decide how those paths may be read, changed, or used by commands.

    workspace = LittleGhost::Workspace.new(root: "./tmp/support-run")
    workspace.root # => an absolute path ending in "/tmp/support-run"

Workspaces participate in the Run resource lifecycle, but object lifetime and
file lifetime are separate. Opening creates `root` and relative named paths,
but does not delete them by default. Absolute named paths are trusted
references that must already exist. Setup and teardown callbacks let trusted
application configuration provision run-scoped resources without a Workspace
subclass. Applications that share a writable root between Runs must provide
their own concurrency and tenant isolation.

See the [Workspaces and Sandboxes guide](../sandboxing.md)
for logical paths, Sandbox policy, process ownership, and networking.

## Inheritance

`LittleGhost::Workspace < Object`

## Attributes

<a id="attribute-i-paths"></a>
### `paths` (R)

Immutable named absolute paths owned by this workspace declaration.

<a id="attribute-i-root"></a>
### `root` (R)

Absolute filesystem root assigned to this workspace.

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(root:, paths: {}, setup: nil, teardown: nil)
```

Expands `root` and every named path to absolute paths. Relative named paths
must remain beneath `root`; absolute named paths deliberately refer outside
it. `setup` receives `workspace:` and `run:` when the
Run opens. `teardown` receives the same values when it closes, including after
partial setup.

<a id="method-c-register_provider"></a>
### `.register_provider`

```ruby
.register_provider(name, implementation)
```

Registers a trusted workspace provider under a configuration symbol.

<a id="method-c-resolve_provider"></a>
### `.resolve_provider`

```ruby
.resolve_provider(name)
```

Resolves an explicitly selected provider without changing its meaning.

## Instance methods

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

Calls the application teardown callback once. The default does not remove
files or directories.

<a id="method-i-environment"></a>
### `#environment`

```ruby
#environment()
```

Environment variables supplied to sandboxed programs. These values are trusted
process configuration and are never returned by filesystem tools.

<a id="method-i-open"></a>
### `#open`

```ruby
#open(run: nil)
```

Calls the application setup callback once and returns this workspace.

<a id="method-i-path"></a>
### `#path`

```ruby
#path(name)
```

Returns a configured named path, raising KeyError when it is absent.

<a id="method-i-reference"></a>
### `#reference`

```ruby
#reference(physical_path)
```

Returns the stable logical reference for a physical workspace path.

<a id="method-i-resolve"></a>
### `#resolve`

```ruby
#resolve(reference)
```

Converts a logical path to its physical workspace path. This method checks
lexical containment but does not make direct filesystem access safe for
untrusted input. Pass model-selected paths through Sandbox file operations,
which reject symlinks while opening each path component.

Relative paths belong to `root`; named paths use
`workspace://name/path`. Physical absolute paths are deliberately
rejected so brokered tools do not teach callers host filesystem layout.

<a id="method-i-validate-21"></a>
### `#validate!`

```ruby
#validate!()
```

Verifies that no configured directory was replaced after #open.