Struct WorkspaceRoot 

pub struct WorkspaceRoot { /* private fields */ }

The server’s one workspace root, resolved once and read everywhere.

Carries the RESULT of resolution rather than requiring it: a server whose home cannot resolve must still boot (nothing else needs the root), so the failure is held here and surfaces as a terminal refusal at the first dispatch of a placeholder-bearing body.

Implementations

impl WorkspaceRoot

pub fn resolve() -> Self

Resolve the workspace root from the server’s aion home: crate::config::aion_home → <home>/clones.

This is the ONE derivation of the value. Everything downstream — the declared-body dispatcher, the startup banner, any composition point reading the banner — consumes the resolved value rather than re-deriving it, so two components can never disagree about where workspaces live.

pub const fn from_resolution( resolution: Result<PathBuf, WorkspaceRootError>, ) -> Self

Build a root from an already-decided resolution.

For embedders and tests that need a known root (or a known failure) without touching the process environment the production WorkspaceRoot::resolve reads. Single derivation is a convention the production path upholds, not an enforced invariant: nothing stops a caller constructing a second, disagreeing root here.

pub fn banner_value(&self) -> String

The one-line rendering of this root for the startup banner: the resolved path’s display form, or unresolvable: <reason> when resolution failed — never a fabricated value.

pub fn resolved(&self) -> Result<&Path, &WorkspaceRootError>

The resolved root, or why there is none.

Read-only: reporting the value (the startup banner) must not create the directory. Creation happens at expansion time, where a failure has a dispatch to refuse.

Errors

Returns the held WorkspaceRootError when resolution failed.

pub fn expand( &self, command: &str, ) -> Result<Option<ExpandedCommand>, WorkspaceRootError>

Expand every WORKSPACE_ROOT_PLACEHOLDER occurrence in command with the resolved root.

A command without the placeholder is untouched — Ok(None), no resolution requirement, no filesystem side effect — so an unresolved root never affects a body that does not use it. A command WITH the placeholder requires the full chain: every occurrence standing alone as one whole, unquoted argv word, then a resolved, absolute, UTF-8 root with no shape-changing characters, and an existing directory (created here, idempotently and owner-only 0700, if missing — an already-existing root keeps whatever permissions the operator gave it; they are the operator’s own).

Errors

Returns WorkspaceRootError when a placeholder occurrence is not a whole unquoted argv word, when the root is unresolved, not absolute, not valid UTF-8, contains a character that would change the command’s parsed shape, or does not exist and cannot be created.

pub fn expand_setting( &self, value: &str, ) -> Result<Option<String>, WorkspaceRootError>

Expand every WORKSPACE_ROOT_PLACEHOLDER occurrence in a harness section’s PATH-VALUED setting — an ACP command, either kind’s cwd, a Norn binary — with the resolved root.

A value without the placeholder is untouched: Ok(None), no resolution requirement, no filesystem side effect. A document that names an absolute path outright is therefore unaffected by an unresolvable root, exactly as it is unaffected by one today.

The rules that govern WorkspaceRoot::expand’s COMMAND splice are deliberately NOT applied here, because a setting is not a command:

• No placeholder-placement rule. A command is split into argv words, so an occurrence glued to other text would splice a fragment of some larger word. A setting is one whole value that nothing splits, so {workspace_root}/agents is the ordinary way to write it. Where the placeholder may stand is the LANGUAGE’s rule, refused at aion_awl::harness_path_form — it must lead the value — and this layer does not restate it.
• No shape-changing-character rule, save NUL. Whitespace, $ and quotes change how a command PARSES; a directory named /Users/a b is simply a directory, and refusing it here would refuse a legitimate path for a reason that belongs to a different consumer. NUL survives the cut on its own footing: execve cannot carry it.

The ROOT directory is created (idempotently, owner-only 0700) exactly as the command path creates it, and for the harder reason: a process cannot be started in a directory that does not exist. Only the root — a value naming something BENEATH it ({workspace_root}/assistant) is the document’s claim about a tree that should already be there, and conjuring an empty one would turn a mistyped path into an agent working against nothing. The adapter refuses a missing working directory by name, before it spawns.

Errors

Returns WorkspaceRootError when the root is unresolved, not absolute, not valid UTF-8, carries a NUL byte, or does not exist and cannot be created. Every one of them is terminal — the root is a property of this box’s configuration and filesystem, so a second attempt reads the same answer.

Trait Implementations

impl Clone for WorkspaceRoot

fn clone(&self) -> WorkspaceRoot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WorkspaceRoot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.