Filesystem conventions for Pixir.
Two roots (ADR 0002 / 0003):
- Global
~/.pixir/— cross-project, user-level state:auth.json,config.json. Created lazily,0700. - Project
.pixir/— per-Workspace state, rooted at the current working directory. Sessions live in.pixir/sessions/<id>.ndjsonand are the source of truth for the Log. Session writer leases live under.pixir/session_leases/and are live-capability evidence, not History. Session Resources live next to the Log under.pixir/sessions/<id>/resources/. This subtree is gitignored.
Path builders return absolute paths. Content-bearing Log and lease callers use the structured state-path helpers below before their filesystem operations. Session Resource payload-path hardening is a documented deferred boundary.
The Workspace root itself is the trusted anchor, including a deliberate symlink alias.
Below that anchor, Pixir performs lstat-based component checks and refuses existing
or dangling symlinks. This is a static tripwire, not a same-UID race-free guarantee:
another process may still replace a component between check and use.
Summary
Types
Observed state of the final component of a checked Pixir state path.
Functions
Global auth.json path (OAuth credentials).
Global config.json path.
Ensure the global root exists (mode 0700) and return it.
Ensure the Session writer lease releases dir exists and return it.
Ensure the Session writer lease dir exists and return it.
Ensure the Session Resources dir exists and return it.
Ensure the project sessions dir exists and return it.
Create a Pixir-owned directory one component at a time below the trusted Workspace.
Global root: ~/.pixir (override with PIXIR_HOME).
Pixir-global Skills root: ~/.pixir/skills (respects PIXIR_HOME).
Inspect every component below the trusted Workspace root with File.lstat/1.
Require a checked Pixir state path's final component to be absent.
Check a Pixir state path, allowing the final component to be absent.
Project root: <workspace>/.pixir (workspace defaults to cwd).
Writer lease path for a given Session id.
Directory for Session writer lease diagnostic records.
Project Session writer lease directory: <workspace>/.pixir/session_leases.
NDJSON Log path for a given session id.
Directory for durable Session Resources attached to a Session.
Project sessions directory: <workspace>/.pixir/sessions.
Types
@type state_path_state() :: :missing | :regular | :directory | atom()
Observed state of the final component of a checked Pixir state path.
Functions
@spec auth_file() :: String.t()
Global auth.json path (OAuth credentials).
@spec config_file() :: String.t()
Global config.json path.
@spec ensure_global_root() :: String.t()
Ensure the global root exists (mode 0700) and return it.
Ensure the Session writer lease releases dir exists and return it.
Ensure the Session writer lease dir exists and return it.
Ensure the Session Resources dir exists and return it.
Ensure the project sessions dir exists and return it.
Create a Pixir-owned directory one component at a time below the trusted Workspace.
Each existing or newly created component is verified with lstat; mkdir_p is not
used, so a pre-existing symlink cannot be followed while creating deeper state.
@spec global_root() :: String.t()
Global root: ~/.pixir (override with PIXIR_HOME).
@spec global_skills_dir() :: String.t()
Pixir-global Skills root: ~/.pixir/skills (respects PIXIR_HOME).
@spec inspect_state_path(String.t(), String.t(), keyword()) :: {:ok, %{path: String.t(), state: state_path_state()}} | {:error, map()}
Inspect every component below the trusted Workspace root with File.lstat/1.
:expected may be :any, :regular, or :directory. Missing paths are reported as
state: :missing; existing symlinks, non-directory ancestors, unexpected final types,
and lstat failures return structured :unsafe_state_path errors without following or
reading a target.
Require a checked Pixir state path's final component to be absent.
Check a Pixir state path, allowing the final component to be absent.
Project root: <workspace>/.pixir (workspace defaults to cwd).
Writer lease path for a given Session id.
Directory for Session writer lease diagnostic records.
Project Session writer lease directory: <workspace>/.pixir/session_leases.
NDJSON Log path for a given session id.
Directory for durable Session Resources attached to a Session.
Project sessions directory: <workspace>/.pixir/sessions.