Alien‑Filesystem: Unified Four‑Phase Repository

Scope: Standalone, read‑only, multi‑repo virtual filesystem for AI‑Chat navigation, indexing, graphing, and terminal‑less execution.
Constraint: No Artemis coupling; scoped strictly to Alien‑Filesystem itself.
Blacklist: DocLink, Blake, DocRef, SAFEHALT, FAULT, CRS tokens MUST NOT be used as operational commands.

---

1. Repository Layout (Phases 1–4)

Alien-Filesystem/
├── Cargo.toml
├── .gitignore
├── README.md
├── SOVEREIGNTY.md
├── alienfs-config.toml
├── specs/
│   ├── AlienFSMountSpec2026v1.aln
│   ├── AlienFSSearchIndex2026v1.aln
│   ├── AlienFSGraphSchema2026v1.aln
│   ├── AlienFSAIChatSurface2026v1.aln
│   └── AlienFSSandboxToolingPolicy2026v1.aln
├── crates/
│   ├── alienfs-core/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── error.rs
│   │       ├── backend.rs
│   │       ├── path.rs
│   │       ├── github.rs
│   │       ├── local.rs
│   │       ├── readonly.rs
│   │       ├── config.rs
│   │       └── mount.rs
│   ├── alienfs-index/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── error.rs
│   │       ├── schema.rs
│   │       ├── builder.rs
│   │       ├── query.rs
│   │       ├── result.rs
│   │       ├── governance.rs
│   │       └── parsers/
│   │           ├── mod.rs
│   │           ├── rust.rs
│   │           ├── toml.rs
│   │           └── aln.rs
│   ├── alienfs-graph/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── graph.rs
│   │       ├── cargo.rs
│   │       ├── aln.rs
│   │       ├── docs.rs
│   │       └── export.rs
│   └── alienfs-ai/
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs
│           ├── client.rs
│           ├── mcp.rs
│           ├── config.rs
│           └── api/
│               ├── mod.rs
│               ├── read.rs
│               ├── search.rs
│               └── graph.rs
├── src/
│   └── main.rs
├── docs/
│   ├── architecture/
│   │   ├── alienfs-core-architecture.md
│   │   ├── alienfs-index-architecture.md
│   │   ├── alienfs-graph-architecture.md
│   │   ├── alienfs-ai-architecture.md
│   │   └── aaf-constellation.mmd
│   ├── development/
│   │   ├── alienfs-developer-guide.md
│   │   └── alienfs-sandbox-toolchain-policy.md
│   ├── howto/
│   │   ├── alienfs-mount-recipes.md
│   │   └── alienfs-index-operations.md
│   ├── integration/
│   │   └── alienfs-ai-mcp-guide.md
│   └── governance/
│       └── alienfs-governance-primer.md
└── tests/
    ├── integration/
    │   ├── mount_resolution.rs
    │   ├── path_confinement.rs
    │   ├── search_governance.rs
    │   └── graph_export.rs
    └── fixtures/
        ├── sample-repo/
        └── sample-aln/

---

2. Workspace and Dependencies

Root Cargo.toml:

[workspace]
members = [
  "crates/alienfs-core",
  "crates/alienfs-index",
  "crates/alienfs-graph",
  "crates/alienfs-ai",
]
resolver = "2"

[workspace.dependencies]
octocrab = "^0.38"
camino = "^1.1"
rusqlite = { version = "^0.32", features = ["bundled", "fts5"] }
tree-sitter = "^0.22"
tree-sitter-rust = "^0.21"
tree-sitter-toml = "^0.21"
petgraph = "^0.6"
serde = "^1.0"
toml = "^0.8"
tempfile = "^3.10"
mcp-server = "^0.2"
walkdir = "^2.5"
anyhow = "^1.0"
thiserror = "^1.0"

[profile.sandbox]
inherits = "dev"
opt-level = 1
debug = true
incremental = false
lto = "off"
codegen-units = 4

The sandbox profile is intended for disk‑constrained environments and AI‑Chat sandboxes.

---

3. Phase 1: Core VFS (alienfs‑core)

Core VFS traits and backends live in crates/alienfs-core.

Key concepts:

• VfsBackend: read‑only abstraction over backing storage (GitHub or local).
• VfsPath: normalized, UTF‑8, mount‑confined path type with no traversal escapes.
• ReadOnlyVfs<B>: public surface for all later phases; only read, readdir, metadata.

Example VfsBackend surface:

pub struct DirEntry {
    pub name: String,
    pub path: String,
    pub is_dir: bool,
    pub size_bytes: Option<u64>,
}

pub struct Metadata {
    pub size_bytes: u64,
    pub modified: Option<std::time::SystemTime>,
    pub is_file: bool,
    pub is_dir: bool,
}

pub trait VfsBackend: Send + Sync {
    fn read(&self, path: &str) -> anyhow::Result<Vec<u8>>;
    fn read_dir(&self, path: &str) -> anyhow::Result<Vec<DirEntry>>;
    fn metadata(&self, path: &str) -> anyhow::Result<Metadata>;
}

ReadOnlyVfs uses VfsPath and AlienFSMountSpec2026v1.aln to guarantee confinement.

---

4. Phase 2: Indexing (alienfs‑index)

The indexing layer lives in crates/alienfs-index and builds a governed SQLite index with FTS5 and symbol extraction.

Core types (query.rs, result.rs):

pub enum SearchKind {
    File,
    Symbol,
    Dependency,
    Config,
    AlnDoctype,
}

pub struct GovernanceFilter {
    pub roh_max: f32,
    pub veco_max: f32,
    pub lyap_min: f32,
    pub kerk_min: f32,
    pub kere_min: f32,
    pub kerr_max: f32,
}

pub struct SearchQuery {
    pub text: String,
    pub kind_filter: Option<SearchKind>,
    pub repo_filter: Option<String>,
    pub max_results: usize,
    pub governance_filter: Option<GovernanceFilter>,
}

pub struct GovernanceMetadata {
    pub roh: f32,
    pub veco: f32,
    pub lyapunov: f32,
    pub kerk: f32,
    pub kere: f32,
    pub kerr: f32,
}

pub struct SearchResult {
    pub path: String,
    pub kind: SearchKind,
    pub line: Option<u32>,
    pub snippet: String,
    pub relevance: f32,
    pub governance: Option<GovernanceMetadata>,
    pub crossrefs: Vec<String>,
}

The index is built via IndexBuilder over ReadOnlyVfs, using parsers for Rust, TOML, and ALN to populate files, filesfts, symbols, and dependencies. Governance caps for each file come from AlienFSMountSpec2026v1.aln and are enforced during search.

---

5. Phase 3: Graph (alienfs‑graph)

Graph construction lives in crates/alienfs-graph and builds a dependency and documentation graph over crates, specs, and source files.

Core types (graph.rs):

pub enum NodeKind {
    WorkspaceRoot,
    Crate,
    AlnShard,
    SpecDoc,
    ConfigFile,
    SourceFile,
    Symbol,
}

pub enum EdgeKind {
    DependsOn,
    Declares,
    Implements,
    Documents,
    MountedAt,
    IndexedAs,
}

pub struct GraphNode {
    pub id: String,
    pub kind: NodeKind,
    pub path: Option<String>,
    pub governance: GovernanceMetadata,
}

pub struct DependencyGraph {
    pub graph: petgraph::stable_graph::StableGraph<GraphNode, EdgeKind>,
    pub node_index: std::collections::HashMap<String, petgraph::stable_graph::NodeIndex>,
}

The graph is derived from the VFS, Cargo metadata, ALN specs, and the index, and can be exported as Mermaid or JSON for AI‑Chat navigation.

---

6. Phase 4: AI‑Chat Surface (alienfs‑ai and binary)

The AI surface and MCP server live in crates/alienfs-ai and src/main.rs.

Client facade (client.rs):

pub struct AlienFsClient {
    pub vfs: ReadOnlyVfs<impl VfsBackend>,
    pub index: SearchIndex,
    pub graph: DependencyGraph,
}

impl AlienFsClient {
    pub fn new_from_config(config_path: &str) -> anyhow::Result<Self>;
    pub async fn read_file(&self, path: &str) -> anyhow::Result<FileResponse>;
    pub async fn search(&self, query: &str, kind: Option<SearchKind>) -> anyhow::Result<Vec<SearchResult>>;
    pub async fn get_dependencies(&self, node: &str) -> anyhow::Result<Vec<String>>;
    pub async fn get_graph_mermaid(&self) -> anyhow::Result<String>;
}

Binary entry (src/main.rs):

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config_path = std::env::var("ALIENFS_CONFIG")
        .unwrap_or_else(|_| "alienfs-config.toml".to_string());

    let client = AlienFsClient::new_from_config(&config_path)?;
    let server = alienfs_ai::mcp::AlienFsMcpServer::new(client);

    mcp_server::stdio::serve(server).await?;
    Ok(())
}

The MCP server exposes tools such as alienfs.read, alienfs.search, alienfs.symbolinfo, and alienfs.crossrefs, governed by AlienFSAIChatSurface2026v1.aln.

---

7. ALN Spec Highlights

7.1 Mount Spec (specs/AlienFSMountSpec2026v1.aln)

Defines the mount universe for Phase 1:

• Backends: LOCAL, GITHUB.
• Mount roots and allowed prefixes.
• Per‑mount governance caps (RoH, Veco, Lyapunov) constrained by the global corridor.

7.2 Search Index Spec (specs/AlienFSSearchIndex2026v1.aln)

Defines:

• SearchKind, SearchQuery, SearchResult.
• Governance invariants: all results must satisfy the global corridor.
• FTS and symbol uniqueness invariants.

7.3 Graph Schema (specs/AlienFSGraphSchema2026v1.aln)

Defines:

• NodeKind, EdgeKind.
• Graph invariants: nodes must correspond to VFS or index entries; governance is propagated.

7.4 AI Surface (specs/AlienFSAIChatSurface2026v1.aln)

Defines:

• Allowed MCP operations (read, search, graph, optional link tools).
• Token budgets and governance envelopes per operation.
• Sandbox binding records for the MCP environment class.

7.5 Sandbox Tooling Policy (specs/AlienFSSandboxToolingPolicy2026v1.aln)

Defines:

• Sandbox environment classes (e.g., TINY-SANDBOX).
• Tooling policy flags for each class.
• Invariants that forbid toolchain installation inside tiny sandboxes.

---

8. Build and Execution

On a host with a pre‑installed Rust toolchain:

# Phase 1: core VFS tests
cargo test -p alienfs-core

# Phase 2: build and run indexer
cargo build -p alienfs-index --release
cargo run -p alienfs-index --bin alienfs-index -- \
  --config alienfs-config.toml \
  --output target/alienfs-index.db \
  --mount-id ALIENFS-SELF

# Phase 3: graph build and export
cargo build -p alienfs-graph --release
cargo run -p alienfs-graph -- --config alienfs-config.toml \
  --index target/alienfs-index.db \
  --export-mermaid docs/architecture/aaf-constellation.mmd

# Phase 4: MCP server for AI‑Chat
cargo build -p alienfs-ai --release
cargo run -p alienfs-ai --bin alienfs -- --serve --config alienfs-config.toml

On constrained sandboxes, prefer:

cargo build -p alienfs-index --profile sandbox

and per‑crate builds rather than workspace‑wide builds.

---

9. Toolchain Policy in Sandboxes

Alien‑Filesystem is designed to run in sandboxes where the Rust toolchain is provisioned by the host. In such environments:

• Do not run rustup install, rustup update, or rustup toolchain install.
• Do not run curl‑based installers (for example, curl https://sh.rustup.rs | sh).
• Do not attempt to change the toolchain via cargo +nightly or cargo +beta.

Coding agents and CI jobs MUST:

1. Check whether cargo and rustc are present.
2. Use them as‑is if available.
3. If they are missing, report that the host toolchain must be installed or fixed outside the sandbox, rather than attempting in‑sandbox installation.

The docs/development/alienfs-sandbox-toolchain-policy.md document and AlienFSSandboxToolingPolicy2026v1.aln shard describe this policy formally.

---

10. Governance and Invariants

Alien‑Filesystem is governed by a global corridor over a six‑component governance vector (RoH, Veco, Lyapunov, K, E, R). All mounts, index rows, search results, and graph nodes must lie within this corridor, and the system enforces:

• Read‑only VFS by design.
• Path confinement via VfsPath normalization.
• Governance filtering at query‑time.
• Stability limits for indexing operations.
• Token‑efficient search and graph exports for AI‑Chat.

---

11. Conquering Hex Grounding String

0x414c49454e46535f414c49454e2d46494c4553595354454d5f504841534553315f345f636f72652b696e6465782b67726170682b61695f737572666163655f726561646f6e6c795f7666732b616c6e5f73706563735f666f725f616c69656e66735f7265706f5f6f6e6c79

This repository provides a complete, read‑only, governance‑aware navigation layer across all four phases, suitable for AI‑Chat agents and human developers operating in both full and constrained environments.