cppalliance · vinniefalco · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,11 +2,36 @@
 
 Multi-crate Rust workspace for the PromptForge pipeline runtime, inference gateway, and Workshop desktop product.
 
+## Principles
+
+- Do more with less. Prefer simple, foundational primitives over specific solutions: a primitive that naturally enables today's functionality and also generalizes beats a custom mechanism specified as a laundry list of requirements. Generality is the payoff, not a goal.
+- When evaluating how to implement a capability, check whether the existing facilities subsume the work before building new machinery. Prioritize in this order:
+  1. Reuse an existing facility
+  2. Make the smallest improvement to an existing facility which enables the capability.
+  3. Add a new facility. New machinery must have a material benefit beyond tidiness.
+- When improving an existing facility, prefer an improvement that serves a problem class beyond the current case over one that solves only the case at hand, when the general shape costs no more.
+
+## Roles
+
+- Workshop is a user-facing agentic development environment: a Tauri desktop application with an HTML/CSS/TypeScript UI
+- PromptForge is the runtime execution engine for the PromptForge Prompting Language: structured Markdown files with live Lua code fences
+- Gateway is an independent service that proxies local and remote inference through one OpenAI-compatible HTTP and WebSocket endpoint
+
+## Structure
+
+- The three main products are PromptForge, Gateway, and Workshop
+- Workshop crates are named workshop-* and must not depend on gateway crates
+- Gateway crates are named gateway-* and must not depend on promptforge or workshop crates
+- PromptForge crates are named promptforge-* and must not depend on gateway or workshop crates
+- Shared crates are named shared-*, contain the public API surface across products and downstream crates, and must not depend on any product crates
+- Crates named build-* are for building specific outputs
+- Dependency rules bind all kinds: normal, dev, build, and target-specific dependencies
+
+## Engineering
+
 - Prefer types and compiler checks, then behavior tests and deterministic fault injection. Add a structural check only with explicit user approval for a stable product or security boundary that has no ordinary equivalent.
 - Repository policy binds plans. A plan cannot introduce a source parser, snapshot, allowlist, count, ceiling, topology check, import walker, or other structural enforcement unless the user explicitly approves that exception.
 - Behavior changes ship with tests in the same change. Preserve product and behavior tests during refactors. Structural tests that an approved plan identifies as unsupported may be removed without replacement by another structural proxy.
-- Keep four cross-product dependency rules: Gateway product crates cannot depend on Workshop product crates; PromptForge product crates cannot depend on Gateway or Workshop product crates; Gateway product crates cannot depend on PromptForge product crates; Workshop product crates cannot depend on Gateway product crates.
-- Do more with less. Before adding a frontmatter field, configuration key, public type, or resolution path, determine whether sandboxed Lua, the run-scoped store, or the catalog already carries the work. New machinery must have a material benefit beyond tidiness.
 - A Cargo feature gates a real constraint such as a toolchain requirement or heavy native build. It does not describe product shape. Feature-disabled builds must not leak optional types into core paths.
 - Runtime and serve paths never compile native dependencies or invoke build tools. Library and serve paths return failures instead of exiting the process or installing process-global state.
 - Long-running work reports through `shared-progress`. Producers report operation state, hosts forward it, and renderers format it.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -28,15 +28,17 @@ gateway-config-ui = { path = "crates/gateway-config-ui", version = "0.3.0" }
 gateway-local = { path = "crates/gateway-local", version = "0.3.0" }
 gateway-logging = { path = "crates/gateway-logging", version = "0.3.0" }
 shared-loopback = { path = "crates/shared-loopback", version = "0.3.0" }
-shared-protocol = { path = "crates/shared-protocol", version = "0.3.0" }
+gateway-protocol = { path = "crates/gateway-protocol", version = "0.3.0" }
 shared-sidecar = { path = "crates/shared-sidecar", version = "0.3.0" }
+shared-vfs = { path = "crates/shared-vfs", version = "0.3.0" }
 gateway-routing = { path = "crates/gateway-routing", version = "0.3.0" }
 promptforge-lua = { path = "crates/promptforge-lua", version = "0.3.0" }
 promptforge-model-client = { path = "crates/promptforge-model-client", version = "0.3.0" }
 promptforge-parser = { path = "crates/promptforge-parser", version = "0.3.0" }
 shared-progress = { path = "crates/shared-progress", version = "0.3.0" }
 gateway-stt = { path = "crates/gateway-stt", version = "0.3.0" }
 promptforge-store = { path = "crates/promptforge-store", version = "0.3.0" }
+promptforge-vfs = { path = "crates/promptforge-vfs", version = "0.3.0" }
 promptforge-webfetch = { path = "crates/promptforge-webfetch", version = "0.3.0" }
 promptforge-tool-picker = { path = "crates/promptforge-tool-picker", version = "0.3.0" }
 promptforge-tools = { path = "crates/promptforge-tools", version = "0.3.0" }

diff --git a/crates/gateway-config/src/config.rs b/crates/gateway-config/src/config.rs
@@ -19,8 +19,6 @@ pub use companion::{
     SpeculativeConfig,
 };
 pub(crate) use imp::reject_profiles_directory;
-#[cfg(test)]
-pub(crate) use interpolate::interpolate;
 pub(crate) use interpolate::interpolate_value;
 use stt::RawSttPipelineConfig;
 pub use stt::{

diff --git a/crates/gateway-config/src/config/tests.rs b/crates/gateway-config/src/config/tests.rs
@@ -1,3 +1,4 @@
+use super::interpolate::interpolate;
 use super::*;
 
 const SAMPLE: &str = r#"

diff --git a/crates/gateway-local/Cargo.toml b/crates/gateway-local/Cargo.toml
@@ -16,7 +16,7 @@ documentation = "https://cppalliance.github.io/promptforge/"
 async-trait.workspace = true
 flate2.workspace = true
 gateway-config.workspace = true
-shared-protocol.workspace = true
+gateway-protocol.workspace = true
 gateway-routing.workspace = true
 shared-progress.workspace = true
 rand.workspace = true

diff --git a/crates/gateway-local/src/artifacts.rs b/crates/gateway-local/src/artifacts.rs
@@ -14,7 +14,7 @@
 
 mod archive;
 mod assets;
-mod confine;
+pub(crate) mod confine;
 mod digest;
 mod download;
 mod progress;
@@ -33,8 +33,6 @@ use tokio_util::sync::CancellationToken;
 
 use crate::error::LocalError;
 
-#[cfg(test)]
-use archive::extract_archive;
 use archive::extract_archive_with_progress;
 use archive::find_executable;
 use archive::require_executable;
@@ -56,10 +54,6 @@ pub(crate) use confine::{
     enforce_private_cache_root, ensure_cache_directory, part_path, remove_cache_entry,
     rename_confined, safe_relative_path, validate_cache_path, write_synced,
 };
-// Test builds only: the resume tests in this module and cache.rs build the
-// marker path; the download path itself imports it from confine directly.
-#[cfg(test)]
-pub(crate) use confine::source_marker_path;
 pub(crate) use digest::hex_digest;
 pub use digest::parse_expected_digest;
 pub(crate) use download::{download_with_progress, hub_bearer_token_from_env};

diff --git a/crates/gateway-local/src/artifacts/tests.rs b/crates/gateway-local/src/artifacts/tests.rs
@@ -10,8 +10,9 @@ use tempfile::TempDir;
 use shared_progress::{EventState, ProgressHub};
 use tokio_util::sync::CancellationToken;
 
-use super::archive::{extract_archive_with_progress, safe_archive_path};
+use super::archive::{extract_archive, extract_archive_with_progress, safe_archive_path};
 use super::assets::ArchiveRef;
+use super::confine::source_marker_path;
 use super::digest::file_digest;
 use super::download::{hub_bearer_token, is_huggingface_https};
 use super::progress::{DownloadProgress, TreeProgress};

diff --git a/crates/gateway-local/src/cache.rs b/crates/gateway-local/src/cache.rs
@@ -615,7 +615,7 @@ mod tests {
     use tempfile::TempDir;
 
     use super::*;
-    use crate::artifacts::source_marker_path;
+    use crate::artifacts::confine::source_marker_path;
     use crate::testsupport::{FakeServer, hex_sha256};
 
     /// Test double recording the progress callbacks a download drives.

diff --git a/crates/gateway-local/src/dialect.rs b/crates/gateway-local/src/dialect.rs
@@ -19,7 +19,7 @@ use crate::error::LocalError;
 const PROPS_TIMEOUT: Duration = Duration::from_secs(5);
 
 /// Byte ceiling for a dialect-probe JSON body (HYGIENE-BOUNDS-001).
-const MAX_PROBE_BODY: u64 = shared_protocol::http_util::MAX_JSON_BODY as u64;
+const MAX_PROBE_BODY: u64 = gateway_protocol::http_util::MAX_JSON_BODY as u64;
 
 /// Evidence from a local child's `/props`, `/v1/models`, and sidecar metadata
 /// used to select a tool-calling dialect.

diff --git a/crates/gateway-local/src/lib.rs b/crates/gateway-local/src/lib.rs
@@ -12,7 +12,7 @@
 //! header inspection in [`gguf`].
 //!
 //! Failures are reported as [`LocalError`]; an explicit teardown failure is
-//! reported as [`ShutdownError`](shared_protocol::ShutdownError).
+//! reported as [`ShutdownError`](gateway_protocol::ShutdownError).
 //! The crate contains no HTTP routing and no error envelopes; those live in
 //! the gateway crate.
 

diff --git a/crates/gateway-local/src/runtime.rs b/crates/gateway-local/src/runtime.rs
@@ -14,10 +14,10 @@ use std::thread;
 use std::time::Duration;
 
 use gateway_config::{Config, LocalModelConfig, ModelKind, QueuePolicy, ThinkingMode};
+use gateway_protocol::ShutdownError;
 use gateway_routing::queue::DominionQueue;
 use gateway_routing::{Endpoint, Model, dominion_queues};
 use shared_progress::ProgressHandle;
-use shared_protocol::ShutdownError;
 use tokio_util::sync::CancellationToken;
 
 use crate::artifacts::{self, ArtifactStore, ProvisionedServer, ServerSelection};
@@ -658,7 +658,7 @@ impl LocalRuntime {
 
     /// Removes one started model and its upstream from the runtime, returning
     /// the model so the caller can tear the child down through the
-    /// [`Upstream`](shared_protocol::upstream::Upstream) seam (which disables
+    /// [`Upstream`](gateway_protocol::upstream::Upstream) seam (which disables
     /// respawn before killing the process). Returns `None` when no started
     /// model carries `name`.
     ///
@@ -682,7 +682,7 @@ impl LocalRuntime {
     /// Dropping the runtime does not guarantee child termination, because the
     /// routing table holds `Arc<dyn Upstream>` clones of these same models, so
     /// the runtime is not the sole owner (PFGL-MOD-001). This drives an explicit
-    /// teardown through the [`Upstream`](shared_protocol::upstream::Upstream) seam so a
+    /// teardown through the [`Upstream`](gateway_protocol::upstream::Upstream) seam so a
     /// profile switch frees the old children's VRAM deterministically before the
     /// replacement profile's children start. Every child is torn down even if an
     /// earlier one fails, so one stuck child never strands the rest.

diff --git a/crates/gateway-local/src/server/support.rs b/crates/gateway-local/src/server/support.rs
@@ -18,7 +18,7 @@ use super::{
     SpawnRequest,
 };
 use crate::error::LocalError;
-use shared_protocol::http_util::MAX_JSON_BODY;
+use gateway_protocol::http_util::MAX_JSON_BODY;
 
 /// A spawn callback: builds a child from a [`SpawnRequest`].
 pub(super) type SpawnFn = Box<dyn FnMut(&SpawnRequest<'_>) -> Result<Child> + Send>;