From 8f0b9840f664e165663156804aeeaf863fd9144c Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 21:46:33 -0400
Subject: [PATCH 1/4] feat(runtime): realize sourceos-shell PDF stack config
 surface

---
 modules/nixos/sourceos-shell/default.nix | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index 1be9482..9112e98 100644
--- a/modules/nixos/sourceos-shell/default.nix
+++ b/modules/nixos/sourceos-shell/default.nix
@@ -63,6 +63,21 @@ in
       searchProvider.linuxFileProvider=${cfg.searchProvider.linuxFileProvider}
     '';
 
+    environment.etc."sourceos-shell/pdf-stack.json".text = builtins.toJSON {
+      derive = {
+        service = "sourceos-docd";
+        port = cfg.docdPort;
+      };
+      secure = {
+        service = "sourceos-pdf-secure";
+        port = cfg.pdfSecurePort;
+      };
+      invariants = [
+        "artifact_manifest_required"
+        "signed_and_validation_reports_flow_from_runtime"
+      ];
+    };
+
     environment.etc."sourceos-shell/search-provider.json".text = builtins.toJSON {
       mode = cfg.searchProvider.mode;
       linuxFileProvider = cfg.searchProvider.linuxFileProvider;

From bf6ce70fea95f2f2109336e958b48ccdc24d66a3 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 21:48:21 -0400
Subject: [PATCH 2/4] test(runtime): add sourceos-shell PDF config contract
 check

---
 tests/sourceos-shell-pdf-config-contract.nix | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 tests/sourceos-shell-pdf-config-contract.nix

diff --git a/tests/sourceos-shell-pdf-config-contract.nix b/tests/sourceos-shell-pdf-config-contract.nix
new file mode 100644
index 0000000..61e3cff
--- /dev/null
+++ b/tests/sourceos-shell-pdf-config-contract.nix
@@ -0,0 +1,12 @@
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.runCommand "sourceos-shell-pdf-config-contract" {
+  nativeBuildInputs = [ pkgs.gnugrep ];
+} ''
+  grep -q 'pdf-stack.json' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'service = "sourceos-docd"' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'service = "sourceos-pdf-secure"' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'artifact_manifest_required' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'signed_and_validation_reports_flow_from_runtime' ${../modules/nixos/sourceos-shell/default.nix}
+  mkdir -p $out
+  echo validated > $out/result.txt
+''

From ebca94fc6dd97f2d91894279d4109e5fd18587a3 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 21:51:40 -0400
Subject: [PATCH 3/4] test(runtime): add sourceos-shell PDF config contract
 check to flake

---
 flake.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/flake.nix b/flake.nix
index b9e7ac6..b8bbf6b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -134,6 +134,7 @@
           mesh-host-runtime-contract = import ./tests/mesh-host-runtime-contract.nix { inherit pkgs; };
           sourceos-shell-module-contract = import ./tests/sourceos-shell-module-contract.nix { inherit pkgs; };
           sourceos-shell-pdf-stack-contract = import ./tests/sourceos-shell-pdf-stack-contract.nix { inherit pkgs; };
+          sourceos-shell-pdf-config-contract = import ./tests/sourceos-shell-pdf-config-contract.nix { inherit pkgs; };
 
           meshd-package = self.packages.${system}.meshd;
           meshd-linkd-package = self.packages.${system}.meshd-linkd;

From 1961e75019eec8b56a7ae7e7e2acab056440e8ff Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 21:53:22 -0400
Subject: [PATCH 4/4] docs(runtime): mention realized PDF config surface

---
 docs/sourceos-shell-pdf-stack.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/sourceos-shell-pdf-stack.md b/docs/sourceos-shell-pdf-stack.md
index 18b5a4c..5d025c6 100644
--- a/docs/sourceos-shell-pdf-stack.md
+++ b/docs/sourceos-shell-pdf-stack.md
@@ -11,6 +11,12 @@ The Linux realization currently carries service scaffolds for:
 
 These are represented both as systemd unit files under `linux/systemd/` and as service declarations in `modules/nixos/sourceos-shell/default.nix`.
 
+The Linux realization now also carries a machine-facing config surface at:
+
+- `/etc/sourceos-shell/pdf-stack.json`
+
+This config captures the relationship between the derive lane and the secure/sign-validate lane while the runtime repo is still absent.
+
 ## Intent
 
 This is the Linux realization slice of the broader PDF lane tracked in `#93`.
@@ -19,8 +25,9 @@ The future `SourceOS-Linux/sourceos-shell` runtime repo should own the actual PD
 
 ## Validation scaffold
 
-The current Linux realization adds a dedicated contract-style check at:
+The current Linux realization adds dedicated contract-style checks at:
 
 - `tests/sourceos-shell-pdf-stack-contract.nix`
+- `tests/sourceos-shell-pdf-config-contract.nix`
 
-This check verifies that the PDF-related runtime scaffolds and module hooks remain present and aligned.
+These checks verify that the PDF-related runtime scaffolds, module hooks, and realized config surface remain present and aligned.