refactor(isolation): clarify outer fence ownership

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

architecture/sandbox.md

@@ -84,17 +84,20 @@ replacement from granting authority.
 6. Exec, signaling, PTY, DNS, TCP, and loopback-forwarding operations cross the
    authenticated channel for the lifetime of the sandbox generation.
 
-The shared isolation contract receives only the driver's normalized outer-fence
-guarantees: egress is default-deny, there is no unmanaged egress path, the
-evidence is bound to the sandbox generation, revocation has been verified, and
-controller loss fails closed. A digest commits those guarantees to the native
-driver evidence without teaching the shared contract about container networks,
+The shared isolation contract receives only normalized outer-fence guarantees:
+egress is default-deny, there is no unmanaged egress path, the evidence is bound
+to the sandbox generation, revocation has been verified, and controller loss
+fails closed. A digest commits those guarantees to the native
+evidence without teaching the shared contract about container networks,
 Kubernetes objects, VM devices, or accelerator resources.
 
-Each driver makes that projection explicitly. Non-empty native evidence alone
-does not establish a guarantee:
+The component that owns the outer fence also validates its native evidence and
+makes that projection explicitly. In the current Docker, Podman, Kubernetes,
+and VM placements, that component is the compute driver. A delegated isolation
+backend may own the fence and make the same projection instead. Non-empty native
+evidence alone does not establish a guarantee:
 
-| Driver | Native evidence | Guarantees projected by the driver |
+| Current enforcement owner | Native evidence | Guarantees projected by the owner |
 |---|---|---|
 | Docker | Pinned container ID, `network_mode=none`, and no unexpected network attachments | No workload route establishes default-deny, revocation, and controller-loss behavior; the attachment inspection establishes that no unmanaged route exists. |
 | Podman | Pinned container ID, `--network=none`, and no unexpected network attachments | The same container-network facts establish the same four guarantees. |
@@ -129,7 +132,7 @@ OpenShell uses overlapping controls rather than a single sandbox primitive:
 | Filesystem policy | Landlock restricts the paths the agent can read or write. |
 | Process policy | Sandbox and children run as one immutable non-root identity with zero capabilities. |
 | Seccomp notification | Virtualizes supported INET sockets and sends DNS/TCP decisions to the supervisor without nftables or proxy environment variables. |
-| Driver outer fence | Docker `network_mode=none`, a NIC-less VM, or Kubernetes NetworkPolicy prevents any missed or unsupported kernel path from escaping. |
+| Outer network fence | The component that owns network enforcement prevents any missed or unsupported kernel path from escaping. Current examples are Docker `network_mode=none`, a NIC-less VM, and Kubernetes NetworkPolicy. |
 | Policy proxy | Evaluates destination, binary identity, TLS/L7 rules, SSRF checks, and inference interception. |
 
 The supervisor may enrich baseline filesystem allowances for runtime-required
@@ -230,7 +233,7 @@ cannot transfer that approval to another socket.
 
 The outer fence remains mandatory. If notification handling misses a syscall,
 loses the supervisor, exceeds a bound, or encounters an unsupported socket
-type, the request fails and the driver-owned fence still blocks direct egress.
+type, the request fails and the outer fence still blocks direct egress.
 
 CONNECT and absolute-form forward HTTP are explicit-proxy adapters over the same
 egress pipeline. Each adapter normalizes its request into an egress intent, and

crates/openshell-driver-docker/src/isolation.rs

@@ -52,7 +52,7 @@ impl DockerOuterFenceEvidence<'_> {
             BackendError::Descriptor(format!("encode Docker outer fence evidence: {error}"))
         })?;
         let projection =
-            OuterFenceGuarantees::from_driver_evidence(generation, established, &encoded)?;
+            OuterFenceGuarantees::from_enforcement_evidence(generation, established, &encoded)?;
         projection.validate(generation)?;
         Ok(projection)
     }

crates/openshell-driver-kubernetes/src/isolation.rs

@@ -62,7 +62,7 @@ impl KubernetesOuterFenceEvidence<'_> {
             BackendError::Descriptor(format!("encode Kubernetes outer fence evidence: {error}"))
         })?;
         let projection =
-            OuterFenceGuarantees::from_driver_evidence(generation, established, &encoded)?;
+            OuterFenceGuarantees::from_enforcement_evidence(generation, established, &encoded)?;
         projection.validate(generation)?;
         Ok(projection)
     }

crates/openshell-driver-podman/src/isolation.rs

@@ -56,7 +56,7 @@ impl PodmanOuterFenceEvidence<'_> {
         }
         let encoded = serde_json::to_vec(self).map_err(invalid)?;
         let projection =
-            OuterFenceGuarantees::from_driver_evidence(generation, established, &encoded)
+            OuterFenceGuarantees::from_enforcement_evidence(generation, established, &encoded)
                 .map_err(invalid)?;
         projection.validate(generation).map_err(invalid)?;
         Ok(projection)

crates/openshell-driver-vm/src/isolation/mod.rs

@@ -43,7 +43,7 @@ impl VmOuterFenceEvidence<'_> {
         let encoded = serde_json::to_vec(self).map_err(|error| {
             BackendError::Descriptor(format!("encode VM outer fence evidence: {error}"))
         })?;
-        let projection = OuterFenceGuarantees::from_driver_evidence(
+        let projection = OuterFenceGuarantees::from_enforcement_evidence(
             self.generation,
             established.into_iter().flatten(),
             &encoded,

crates/openshell-isolation-interface/src/contract.rs

@@ -386,43 +386,46 @@ pub trait BoundBoundary: Send {
     async fn confirm(self: Box<Self>) -> Result<ConfirmedBoundary, BackendError>;
 }
 
-/// Backend-neutral guarantees established by the compute driver's outer fence.
+/// Backend-neutral guarantees established by the component that owns the outer
+/// network fence.
 ///
-/// Each driver owns its native evidence schema and the code that validates it.
-/// After validation, the driver projects that evidence into these guarantees
-/// and supplies a digest that binds the original evidence to this generation.
-/// The common runtime only validates and compares this projection; it never
-/// interprets runtime- or accelerator-specific fields.
+/// The enforcement owner may be a compute driver or a delegated isolation
+/// backend. It owns its native evidence schema and the code that validates it.
+/// After validation, it projects that evidence into these guarantees and
+/// supplies a digest that binds the original evidence to this generation. The
+/// common runtime only validates and compares this projection; it never
+/// interprets backend- or runtime-specific fields.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum OuterFenceGuarantee {
     /// No workload packet can leave without an explicit mediated decision.
     DefaultDenyEgress,
-    /// The driver found no network path outside the mediated boundary.
+    /// The enforcement owner found no network path outside the mediated boundary.
     NoUnmanagedEgressPath,
-    /// Previously granted access can be revoked by the driver-owned fence.
+    /// Previously granted access can be revoked by the enforcement owner.
     RevocationVerified,
-    /// Loss of the driver or its controller does not open network access.
+    /// Loss of the fence's controller does not open network access.
     ControllerLossFailsClosed,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct OuterFenceGuarantees {
     /// Sandbox generation for which the evidence was collected.
     pub generation: String,
-    /// Complete set of normalized guarantees established by the driver.
+    /// Complete set of normalized guarantees established by the enforcement owner.
     pub established: BTreeSet<OuterFenceGuarantee>,
-    /// Commitment to the driver-owned native evidence used for this projection.
+    /// Commitment to the enforcement owner's native evidence.
     pub evidence_digest: Sha256Digest,
 }
 
 impl OuterFenceGuarantees {
-    /// Bind the guarantees explicitly established by driver-owned evidence.
+    /// Bind guarantees explicitly established by validated enforcement evidence.
     ///
     /// This constructor deliberately does not infer guarantees from the mere
-    /// presence of evidence. The driver must inspect its native state and
-    /// project each established guarantee before calling this function.
-    pub fn from_driver_evidence(
+    /// presence of evidence. The enforcement owner must inspect its native
+    /// state and project each established guarantee before calling this
+    /// function.
+    pub fn from_enforcement_evidence(
         generation: impl Into<String>,
         established: impl IntoIterator<Item = OuterFenceGuarantee>,
         native_evidence: &[u8],
@@ -529,7 +532,7 @@ pub struct BoundaryConfirmation {
     pub authenticated_supervisor: bool,
     pub session_id: SandboxSessionId,
     pub outer_fence: OuterFenceGuarantees,
-    /// The driver-owned containment primitive terminates the workload when its
+    /// The backend-owned containment primitive terminates the workload when its
     /// Sandbox Runtime exits.
     pub runtime_exit_terminates_workload: bool,
     pub resource_claims: BTreeMap<String, String>,

crates/openshell-isolation-interface/tests/backend_conformance.rs

@@ -369,7 +369,7 @@ fn workload_identity() -> ResolvedWorkloadIdentity {
 }
 
 fn complete_outer_fence(generation: &str, evidence: &[u8]) -> OuterFenceGuarantees {
-    OuterFenceGuarantees::from_driver_evidence(
+    OuterFenceGuarantees::from_enforcement_evidence(
         generation,
         [
             OuterFenceGuarantee::DefaultDenyEgress,
@@ -425,10 +425,10 @@ fn outer_fence_guarantees_are_backend_neutral_and_fail_closed() {
         assert!(incomplete.validate("generation-1").is_err());
     }
 
-    assert!(OuterFenceGuarantees::from_driver_evidence("", [], b"evidence").is_err());
-    assert!(OuterFenceGuarantees::from_driver_evidence("generation-1", [], b"").is_err());
+    assert!(OuterFenceGuarantees::from_enforcement_evidence("", [], b"evidence").is_err());
+    assert!(OuterFenceGuarantees::from_enforcement_evidence("generation-1", [], b"").is_err());
 
-    let unproven = OuterFenceGuarantees::from_driver_evidence(
+    let unproven = OuterFenceGuarantees::from_enforcement_evidence(
         "generation-1",
         [OuterFenceGuarantee::DefaultDenyEgress],
         b"native-driver-evidence",

crates/openshell-sandbox-backend/src/boundary_protocol.rs

@@ -426,7 +426,7 @@ pub struct SandboxRuntimeDescriptor {
     /// example pod UID, VM generation, or container ID).
     #[serde(default)]
     pub resource_claims: std::collections::BTreeMap<String, String>,
-    /// Backend-neutral projection of the driver-validated outer fence.
+    /// Backend-neutral projection of the validated outer network fence.
     pub outer_fence: OuterFenceGuarantees,
 }
 
@@ -494,7 +494,7 @@ pub struct BoundaryConfig {
     pub resource_claim_files: std::collections::BTreeMap<String, PathBuf>,
     /// Exact identity already applied by the runtime to the sandbox process.
     pub workload_identity: openshell_isolation_interface::contract::ResolvedWorkloadIdentity,
-    /// Backend-neutral projection of the driver-validated outer fence.
+    /// Backend-neutral projection of the validated outer network fence.
     pub outer_fence: OuterFenceGuarantees,
     /// Driver-resolved environment exposed only to workload processes.
     #[serde(default)]

crates/openshell-sandbox-backend/src/runtime.rs

@@ -1944,7 +1944,7 @@ mod tests {
     fn test_outer_fence() -> openshell_isolation_interface::contract::OuterFenceGuarantees {
         use openshell_isolation_interface::contract::OuterFenceGuarantee;
 
-        openshell_isolation_interface::contract::OuterFenceGuarantees::from_driver_evidence(
+        openshell_isolation_interface::contract::OuterFenceGuarantees::from_enforcement_evidence(
             "test-generation",
             [
                 OuterFenceGuarantee::DefaultDenyEgress,
@@ -2737,7 +2737,7 @@ mod tests {
     async fn remote_confirm_rejects_outer_fence_digest_mismatch_before_monitoring() {
         let mut confirmation = test_confirmation();
         let different_fence =
-            openshell_isolation_interface::contract::OuterFenceGuarantees::from_driver_evidence(
+            openshell_isolation_interface::contract::OuterFenceGuarantees::from_enforcement_evidence(
                 "test-generation",
                 confirmation.outer_fence.established.iter().copied(),
                 b"different evidence",

crates/openshell-sandbox/src/boundary_server.rs

@@ -4271,7 +4271,7 @@ mod linux {
         fn test_outer_fence() -> openshell_isolation_interface::contract::OuterFenceGuarantees {
             use openshell_isolation_interface::contract::OuterFenceGuarantee;
 
-            openshell_isolation_interface::contract::OuterFenceGuarantees::from_driver_evidence(
+            openshell_isolation_interface::contract::OuterFenceGuarantees::from_enforcement_evidence(
                 "generation-1",
                 [
                     OuterFenceGuarantee::DefaultDenyEgress,