From 3187be9d199f9b816cc19ea65baa596b733eb2fe Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 16 Apr 2026 10:41:54 -0400
Subject: [PATCH 1/2] docs(sourceos): add fog substrate positioning doc

---
 docs/FOG_SUBSTRATE.md | 66 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 docs/FOG_SUBSTRATE.md

diff --git a/docs/FOG_SUBSTRATE.md b/docs/FOG_SUBSTRATE.md
new file mode 100644
index 0000000..260495a
--- /dev/null
+++ b/docs/FOG_SUBSTRATE.md
@@ -0,0 +1,66 @@
+# Fog Substrate Position in SourceOS
+
+This document captures the **OS-substrate responsibilities** for the Fog layer.
+
+`SourceOS` is the immutable, local-first substrate for workstation and edge lanes. The Fog layer depends on this repo for **machine invariants**, not for higher-level distributed semantics.
+
+## What belongs in SourceOS
+
+### 1. Local storage substrate prerequisites
+
+Every eligible SourceOS node/workstation should be able to realize a local storage substrate suitable for ephemeral fog workloads.
+
+This includes:
+- LVM2 availability
+- volume group and thin-pool conventions
+- safe disk targeting rules
+- stable mount-point expectations
+
+### 2. Canonical fog directory contract
+
+The substrate should reserve a stable host-side contract such as:
+
+- `/srv/fog/projects`
+- `/srv/fog/models`
+- `/srv/fog/datasets`
+- `/srv/fog/topics`
+- `/srv/fog/vector`
+- `/srv/fog/cache`
+- `/srv/fog/logs`
+- `/srv/fog/secrets`
+- `/srv/fog/tmp`
+
+These paths are substrate-level invariants so workstation, node, and container lanes can share one filesystem grammar.
+
+### 3. Container-host baseline
+
+SourceOS should define the default local execution posture for fog-capable nodes/workstations:
+- Linux-first container host defaults
+- rootless-friendly execution where possible
+- mount wiring to the fog directory contract
+- no dependency on opt-in community automation
+
+### 4. TopoLVM readiness
+
+When a node participates in Kubernetes lanes, the substrate should provide the prerequisites needed for a local CSI/LVM stack such as TopoLVM.
+
+Important layering rule:
+- local PV provisioning belongs at the substrate/infrastructure layer
+- replication and eventual-consistency semantics belong above the substrate in topic/agent layers
+
+## What does not belong in SourceOS
+
+- topic replication policy semantics
+- Hypercore topic membership logic
+- compute marketplace settlement rules
+- opt-in automation workflows
+
+Those belong in the spec, spine, and automation layers instead.
+
+## Downstream repos expected to refine this
+
+- `SourceOS-Linux/sourceos-spec` — typed contract surface for FogVault / FogCompute
+- `SociOS-Linux/socios-ignition` — first-boot realization of disk/mount/systemd defaults
+- `SociOS-Linux/workstation-contracts` — conformance checks for the machine contract
+- `SociOS-Linux/agentos-spine` — assembled runtime/integration lane
+- `SociOS-Linux/socios` — optional signed catalogs and automation

From 35f348f91006de37c7d4ab5a0a2979503496b210 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 16 Apr 2026 21:07:57 +0000
Subject: [PATCH 2/2] docs: fix markdownlint blank lines in fog substrate doc

Agent-Logs-Url: https://github.com/SociOS-Linux/SourceOS/sessions/c6763b7b-d8bd-47a5-a699-327d2b35525f

Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
---
 docs/FOG_SUBSTRATE.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/FOG_SUBSTRATE.md b/docs/FOG_SUBSTRATE.md
index 260495a..e11467b 100644
--- a/docs/FOG_SUBSTRATE.md
+++ b/docs/FOG_SUBSTRATE.md
@@ -11,6 +11,7 @@ This document captures the **OS-substrate responsibilities** for the Fog layer.
 Every eligible SourceOS node/workstation should be able to realize a local storage substrate suitable for ephemeral fog workloads.
 
 This includes:
+
 - LVM2 availability
 - volume group and thin-pool conventions
 - safe disk targeting rules
@@ -35,6 +36,7 @@ These paths are substrate-level invariants so workstation, node, and container l
 ### 3. Container-host baseline
 
 SourceOS should define the default local execution posture for fog-capable nodes/workstations:
+
 - Linux-first container host defaults
 - rootless-friendly execution where possible
 - mount wiring to the fog directory contract
@@ -45,6 +47,7 @@ SourceOS should define the default local execution posture for fog-capable nodes
 When a node participates in Kubernetes lanes, the substrate should provide the prerequisites needed for a local CSI/LVM stack such as TopoLVM.
 
 Important layering rule:
+
 - local PV provisioning belongs at the substrate/infrastructure layer
 - replication and eventual-consistency semantics belong above the substrate in topic/agent layers