From 8188ee5389b94464d6a38b46657d2f320b01ca1a Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:06:07 -0400
Subject: [PATCH 01/19] test(runtime): add sourceos-shell module contract
 scaffold

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

diff --git a/tests/sourceos-shell-module-contract.nix b/tests/sourceos-shell-module-contract.nix
new file mode 100644
index 0000000..57ce469
--- /dev/null
+++ b/tests/sourceos-shell-module-contract.nix
@@ -0,0 +1,15 @@
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.runCommand "sourceos-shell-module-contract" {
+  nativeBuildInputs = [ pkgs.gnugrep ];
+} ''
+  test -f ${../modules/nixos/sourceos-shell/default.nix}
+  test -f ${../profiles/linux-dev/sourceos-shell.nix}
+  test -f ${../linux/desktop/sourceos-shell.desktop}
+  test -f ${../linux/systemd/sourceos-shell.service}
+  test -f ${../linux/systemd/sourceos-router.service}
+  test -f ${../linux/systemd/sourceos-pdf-secure.service}
+  grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/sourceos-shell.nix}
+  grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
+  mkdir -p $out
+  echo validated > $out/result.txt
+''

From 19b776b5814e25dcd61e1cc6833f1f132ab5ad82 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:12:45 -0400
Subject: [PATCH 02/19] feat(runtime): import sourceos-shell linux-dev profile
 scaffold

---
 profiles/linux-dev/default.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/profiles/linux-dev/default.nix b/profiles/linux-dev/default.nix
index f2ef598..678d171 100644
--- a/profiles/linux-dev/default.nix
+++ b/profiles/linux-dev/default.nix
@@ -2,6 +2,7 @@
 {
   imports = [
     ../../modules/build/default.nix
+    ../../profiles/linux-dev/sourceos-shell.nix
   ];
 
   sourceos.build = {

From cb2313d1af624c8c1f5a5fe350f2cb07de41aaf4 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:15:08 -0400
Subject: [PATCH 03/19] test(runtime): add sourceos-shell module contract check

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

diff --git a/flake.nix b/flake.nix
index 507321e..0d41c44 100644
--- a/flake.nix
+++ b/flake.nix
@@ -65,6 +65,8 @@
             else pkgs.runCommand "stable-x86_64-smoke-skip" {} ''
               mkdir -p $out
             '';
+
+          sourceos-shell-module-contract = import ./tests/sourceos-shell-module-contract.nix { inherit pkgs; };
         });
 
       sourceos = {

From 7cda69249a56cc0b64f6598fe3914bb222f7d0a4 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:17:05 -0400
Subject: [PATCH 04/19] docs(runtime): add launcher bridge note for
 sourceos-shell rollout

---
 docs/sourceos-shell-launcher-bridge.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 docs/sourceos-shell-launcher-bridge.md

diff --git a/docs/sourceos-shell-launcher-bridge.md b/docs/sourceos-shell-launcher-bridge.md
new file mode 100644
index 0000000..c54baf9
--- /dev/null
+++ b/docs/sourceos-shell-launcher-bridge.md
@@ -0,0 +1,19 @@
+# sourceos-shell launcher bridge note
+
+During the early shell rollout, launcher integration is tracked as temporary bridge work.
+
+## Routing rule
+
+Queries are routed by scope:
+
+- `apps` -> launcher or desktop-entry provider
+- `files` -> Linux-native file search only
+- `web` -> browser or web agent
+
+## Required invariant
+
+For `files` queries, Albert must not perform a second file-search pass in parallel with the Linux-native provider.
+
+## Lifecycle
+
+This bridge exists only until the shell's own command/search surface fully absorbs the routing behavior.

From b6667d81995732024d3912d5c021466d4523d326 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:45:06 -0400
Subject: [PATCH 05/19] feat(runtime): add sourceos-docd service scaffold

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

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index 7ae9e9a..08de019 100644
--- a/modules/nixos/sourceos-shell/default.nix
+++ b/modules/nixos/sourceos-shell/default.nix
@@ -73,5 +73,14 @@ in
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-pdf-secure placeholder port=${toString cfg.pdfSecurePort}";
       };
     };
+
+    systemd.services.sourceos-docd = {
+      description = "SourceOS shell docd scaffold";
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        Type = "simple";
+        ExecStart = "${pkgs.coreutils}/bin/echo sourceos-docd placeholder port=${toString cfg.docdPort}";
+      };
+    };
   };
 }

From a26bd667d6087b5c28d70b067503d572539bed27 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:47:09 -0400
Subject: [PATCH 06/19] feat(runtime): add sourceos-docd systemd unit scaffold

---
 linux/systemd/sourceos-docd.service | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 linux/systemd/sourceos-docd.service

diff --git a/linux/systemd/sourceos-docd.service b/linux/systemd/sourceos-docd.service
new file mode 100644
index 0000000..b34e30c
--- /dev/null
+++ b/linux/systemd/sourceos-docd.service
@@ -0,0 +1,13 @@
+[Unit]
+Description=SourceOS docd derive service
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/opt/sourceos-shell/bin/sourceos-docd
+Restart=on-failure
+RestartSec=2s
+
+[Install]
+WantedBy=multi-user.target

From c87a6de041007061d35ad9cfd62d9a5b0656aba7 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:48:12 -0400
Subject: [PATCH 07/19] test(runtime): extend sourceos-shell contract check for
 docd scaffold

---
 tests/sourceos-shell-module-contract.nix | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/sourceos-shell-module-contract.nix b/tests/sourceos-shell-module-contract.nix
index 57ce469..8126ea8 100644
--- a/tests/sourceos-shell-module-contract.nix
+++ b/tests/sourceos-shell-module-contract.nix
@@ -8,8 +8,10 @@ pkgs.runCommand "sourceos-shell-module-contract" {
   test -f ${../linux/systemd/sourceos-shell.service}
   test -f ${../linux/systemd/sourceos-router.service}
   test -f ${../linux/systemd/sourceos-pdf-secure.service}
+  test -f ${../linux/systemd/sourceos-docd.service}
   grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/sourceos-shell.nix}
   grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'sourceos-docd' ${../modules/nixos/sourceos-shell/default.nix}
   mkdir -p $out
   echo validated > $out/result.txt
 ''

From 09646f792d93d221b3a7e34c16d412b719deab45 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:51:28 -0400
Subject: [PATCH 08/19] docs(runtime): mention docd derive service in shell
 integration note

---
 docs/sourceos-shell-integration.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/sourceos-shell-integration.md b/docs/sourceos-shell-integration.md
index b0be40a..9f365a9 100644
--- a/docs/sourceos-shell-integration.md
+++ b/docs/sourceos-shell-integration.md
@@ -11,6 +11,7 @@ This repository, `source-os`, carries the Linux realization surfaces required to
 - Nix/NixOS modules
 - profile wiring
 - machine-level integration hooks
+- derive-service runtime integration such as `docd`
 
 ## What does not belong here
 

From 6bfa0a788aa24f78768d2148fa473467dfb2f616 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:03:28 -0400
Subject: [PATCH 09/19] feat(runtime): add sourceos-shell search-provider
 scaffold

---
 linux/desktop/sourceos-search-provider.conf | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 linux/desktop/sourceos-search-provider.conf

diff --git a/linux/desktop/sourceos-search-provider.conf b/linux/desktop/sourceos-search-provider.conf
new file mode 100644
index 0000000..dc610ce
--- /dev/null
+++ b/linux/desktop/sourceos-search-provider.conf
@@ -0,0 +1,11 @@
+# SourceOS shell search-provider scaffold
+# This file records the intended launcher/search routing policy during early shell rollout.
+
+mode=launcher-bridge
+linux-file-provider=tracker3
+invariant=no_redundant_file_search
+
+# scopes
+apps=launcher
+files=linux-native-only
+web=browser-agent

From bfbe0bbc710a634d47b1e035667487199aa8ace3 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:05:26 -0400
Subject: [PATCH 10/19] feat(runtime): add sourceos-shell search-provider
 options and config

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

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index 08de019..e0e7cc4 100644
--- a/modules/nixos/sourceos-shell/default.nix
+++ b/modules/nixos/sourceos-shell/default.nix
@@ -35,6 +35,20 @@ in
       default = 7073;
       description = "Local port for the sourceos-shell derive/docd service.";
     };
+
+    searchProvider = {
+      mode = lib.mkOption {
+        type = lib.types.enum [ "linux-native" "launcher-bridge" "shell-native" ];
+        default = "launcher-bridge";
+        description = "Search routing mode during shell rollout.";
+      };
+
+      linuxFileProvider = lib.mkOption {
+        type = lib.types.enum [ "tracker3" "fd" "locate" ];
+        default = "tracker3";
+        description = "Linux-native file search provider used when scope=files.";
+      };
+    };
   };
 
   config = lib.mkIf cfg.enable {
@@ -45,8 +59,21 @@ in
       routerPort=${toString cfg.routerPort}
       pdfSecurePort=${toString cfg.pdfSecurePort}
       docdPort=${toString cfg.docdPort}
+      searchProvider.mode=${cfg.searchProvider.mode}
+      searchProvider.linuxFileProvider=${cfg.searchProvider.linuxFileProvider}
     '';
 
+    environment.etc."sourceos-shell/search-provider.json".text = builtins.toJSON {
+      mode = cfg.searchProvider.mode;
+      linuxFileProvider = cfg.searchProvider.linuxFileProvider;
+      invariant = "no_redundant_file_search";
+      scopes = {
+        apps = "launcher";
+        files = "linux-native-only";
+        web = "browser-agent";
+      };
+    };
+
     systemd.services.sourceos-shell = {
       description = "SourceOS shell runtime scaffold";
       wantedBy = [ "multi-user.target" ];

From 93acda1f0d268aff38eca0b8a0e9a57f89355bd9 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:07:04 -0400
Subject: [PATCH 11/19] test(runtime): extend shell contract check for
 search-provider scaffold

---
 tests/sourceos-shell-module-contract.nix | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tests/sourceos-shell-module-contract.nix b/tests/sourceos-shell-module-contract.nix
index 8126ea8..c7027c7 100644
--- a/tests/sourceos-shell-module-contract.nix
+++ b/tests/sourceos-shell-module-contract.nix
@@ -5,6 +5,7 @@ pkgs.runCommand "sourceos-shell-module-contract" {
   test -f ${../modules/nixos/sourceos-shell/default.nix}
   test -f ${../profiles/linux-dev/sourceos-shell.nix}
   test -f ${../linux/desktop/sourceos-shell.desktop}
+  test -f ${../linux/desktop/sourceos-search-provider.conf}
   test -f ${../linux/systemd/sourceos-shell.service}
   test -f ${../linux/systemd/sourceos-router.service}
   test -f ${../linux/systemd/sourceos-pdf-secure.service}
@@ -12,6 +13,8 @@ pkgs.runCommand "sourceos-shell-module-contract" {
   grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/sourceos-shell.nix}
   grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
   grep -q 'sourceos-docd' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'searchProvider' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'no_redundant_file_search' ${../linux/desktop/sourceos-search-provider.conf}
   mkdir -p $out
   echo validated > $out/result.txt
 ''

From dc222145707d0dcf5f32d2486a6257c411e6f8d1 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:08:33 -0400
Subject: [PATCH 12/19] docs(runtime): document search-provider scaffold paths

---
 docs/sourceos-shell-launcher-bridge.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/sourceos-shell-launcher-bridge.md b/docs/sourceos-shell-launcher-bridge.md
index c54baf9..87287df 100644
--- a/docs/sourceos-shell-launcher-bridge.md
+++ b/docs/sourceos-shell-launcher-bridge.md
@@ -14,6 +14,15 @@ Queries are routed by scope:
 
 For `files` queries, Albert must not perform a second file-search pass in parallel with the Linux-native provider.
 
+## Realization scaffolds
+
+The Linux realization currently carries placeholder search-provider material at:
+
+- `linux/desktop/sourceos-search-provider.conf`
+- `/etc/sourceos-shell/search-provider.json` (realized by the shell Nix module scaffold)
+
+These capture the intended rollout mode and the provider choice for the Linux-native file search lane.
+
 ## Lifecycle
 
 This bridge exists only until the shell's own command/search surface fully absorbs the routing behavior.

From 60919b024dfd484f0a17077ba638b2f50cd82b2f Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:12:44 -0400
Subject: [PATCH 13/19] feat(runtime): add sourceos-shell target scaffold

---
 linux/systemd/sourceos-shell.target | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 linux/systemd/sourceos-shell.target

diff --git a/linux/systemd/sourceos-shell.target b/linux/systemd/sourceos-shell.target
new file mode 100644
index 0000000..d3a2937
--- /dev/null
+++ b/linux/systemd/sourceos-shell.target
@@ -0,0 +1,4 @@
+[Unit]
+Description=SourceOS shell service graph
+Wants=sourceos-shell.service sourceos-router.service sourceos-pdf-secure.service sourceos-docd.service
+After=network-online.target

From 9de06b90538c6b681e4df54500ca0031145e564b Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:14:06 -0400
Subject: [PATCH 14/19] feat(runtime): add sourceos-shell systemd target
 scaffold

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

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index e0e7cc4..72dfa3d 100644
--- a/modules/nixos/sourceos-shell/default.nix
+++ b/modules/nixos/sourceos-shell/default.nix
@@ -74,9 +74,17 @@ in
       };
     };
 
+    systemd.targets.sourceos-shell = {
+      description = "SourceOS shell service graph";
+      wants = [ "sourceos-shell.service" "sourceos-router.service" "sourceos-pdf-secure.service" "sourceos-docd.service" ];
+      after = [ "network-online.target" ];
+      wantedBy = [ "multi-user.target" ];
+    };
+
     systemd.services.sourceos-shell = {
       description = "SourceOS shell runtime scaffold";
       wantedBy = [ "multi-user.target" ];
+      partOf = [ "sourceos-shell.target" ];
       serviceConfig = {
         Type = "simple";
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-shell runtime placeholder root=${cfg.packageRoot} port=${toString cfg.shellPort}";
@@ -86,6 +94,7 @@ in
     systemd.services.sourceos-router = {
       description = "SourceOS shell router scaffold";
       wantedBy = [ "multi-user.target" ];
+      partOf = [ "sourceos-shell.target" ];
       serviceConfig = {
         Type = "simple";
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-router placeholder port=${toString cfg.routerPort}";
@@ -95,6 +104,7 @@ in
     systemd.services.sourceos-pdf-secure = {
       description = "SourceOS shell pdf-secure scaffold";
       wantedBy = [ "multi-user.target" ];
+      partOf = [ "sourceos-shell.target" ];
       serviceConfig = {
         Type = "simple";
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-pdf-secure placeholder port=${toString cfg.pdfSecurePort}";
@@ -104,6 +114,7 @@ in
     systemd.services.sourceos-docd = {
       description = "SourceOS shell docd scaffold";
       wantedBy = [ "multi-user.target" ];
+      partOf = [ "sourceos-shell.target" ];
       serviceConfig = {
         Type = "simple";
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-docd placeholder port=${toString cfg.docdPort}";

From f75dc9ee3799db7a149c519fc81db3d250c27cc4 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:15:12 -0400
Subject: [PATCH 15/19] test(runtime): extend shell contract check for service
 graph target

---
 tests/sourceos-shell-module-contract.nix | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/sourceos-shell-module-contract.nix b/tests/sourceos-shell-module-contract.nix
index c7027c7..dc8b6c6 100644
--- a/tests/sourceos-shell-module-contract.nix
+++ b/tests/sourceos-shell-module-contract.nix
@@ -10,11 +10,15 @@ pkgs.runCommand "sourceos-shell-module-contract" {
   test -f ${../linux/systemd/sourceos-router.service}
   test -f ${../linux/systemd/sourceos-pdf-secure.service}
   test -f ${../linux/systemd/sourceos-docd.service}
+  test -f ${../linux/systemd/sourceos-shell.target}
   grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/sourceos-shell.nix}
   grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
   grep -q 'sourceos-docd' ${../modules/nixos/sourceos-shell/default.nix}
   grep -q 'searchProvider' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'systemd.targets.sourceos-shell' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'partOf = \[ "sourceos-shell.target" \]' ${../modules/nixos/sourceos-shell/default.nix}
   grep -q 'no_redundant_file_search' ${../linux/desktop/sourceos-search-provider.conf}
+  grep -q 'sourceos-shell.service sourceos-router.service sourceos-pdf-secure.service sourceos-docd.service' ${../linux/systemd/sourceos-shell.target}
   mkdir -p $out
   echo validated > $out/result.txt
 ''

From f4fd235191500a5a7f2e14812e2227afd70344e4 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 15:15:55 -0400
Subject: [PATCH 16/19] docs(runtime): add sourceos-shell service graph note

---
 docs/sourceos-shell-service-graph.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 docs/sourceos-shell-service-graph.md

diff --git a/docs/sourceos-shell-service-graph.md b/docs/sourceos-shell-service-graph.md
new file mode 100644
index 0000000..79bb9df
--- /dev/null
+++ b/docs/sourceos-shell-service-graph.md
@@ -0,0 +1,18 @@
+# sourceos-shell service graph note
+
+The Linux realization layer currently models the `sourceos-shell` runtime as a four-service graph:
+
+- `sourceos-shell`
+- `sourceos-router`
+- `sourceos-pdf-secure`
+- `sourceos-docd`
+
+These services are grouped by the `sourceos-shell.target` scaffold.
+
+## Intent
+
+This target is a Linux realization placeholder that captures the expected runtime grouping before the actual product/runtime repo exists.
+
+## Follow-on
+
+Once `SourceOS-Linux/sourceos-shell` exists, the placeholder ExecStart values should be replaced with real package/service paths and the current scaffold checks should be upgraded into service-graph checks.

From d90a0c0665357c9fda23a3fe9da25a200c74886d Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 18:49:05 -0400
Subject: [PATCH 17/19] test(runtime): add sourceos-shell service graph
 contract check

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

diff --git a/tests/sourceos-shell-service-graph-contract.nix b/tests/sourceos-shell-service-graph-contract.nix
new file mode 100644
index 0000000..adac31a
--- /dev/null
+++ b/tests/sourceos-shell-service-graph-contract.nix
@@ -0,0 +1,12 @@
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.runCommand "sourceos-shell-service-graph-contract" {
+  nativeBuildInputs = [ pkgs.gnugrep ];
+} ''
+  test -f ${../linux/systemd/sourceos-shell.target}
+  grep -q 'sourceos-shell.service sourceos-router.service sourceos-pdf-secure.service sourceos-docd.service' ${../linux/systemd/sourceos-shell.target}
+  grep -q 'systemd.targets.sourceos-shell' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'partOf = \[ "sourceos-shell.target" \]' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'sourceos-shell.target' ${../docs/sourceos-shell-service-graph.md}
+  mkdir -p $out
+  echo validated > $out/result.txt
+''

From 0a5289c251de4262a4f3f0dd5c25ecbe7d9e1d4f Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 18:49:44 -0400
Subject: [PATCH 18/19] test(runtime): add sourceos-shell service graph
 contract check to flake

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

diff --git a/flake.nix b/flake.nix
index 0d41c44..3a9c42d 100644
--- a/flake.nix
+++ b/flake.nix
@@ -67,6 +67,7 @@
             '';
 
           sourceos-shell-module-contract = import ./tests/sourceos-shell-module-contract.nix { inherit pkgs; };
+          sourceos-shell-service-graph-contract = import ./tests/sourceos-shell-service-graph-contract.nix { inherit pkgs; };
         });
 
       sourceos = {

From 3015d7d6b75fe7aa146112c900f4402d79b8a500 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 18:51:53 -0400
Subject: [PATCH 19/19] docs(runtime): mention service graph contract check

---
 docs/sourceos-shell-service-graph.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/sourceos-shell-service-graph.md b/docs/sourceos-shell-service-graph.md
index 79bb9df..e7df946 100644
--- a/docs/sourceos-shell-service-graph.md
+++ b/docs/sourceos-shell-service-graph.md
@@ -13,6 +13,18 @@ These services are grouped by the `sourceos-shell.target` scaffold.
 
 This target is a Linux realization placeholder that captures the expected runtime grouping before the actual product/runtime repo exists.
 
+## Validation scaffold
+
+The current Linux realization adds a dedicated contract-style check at:
+
+- `tests/sourceos-shell-service-graph-contract.nix`
+
+This check verifies that:
+
+- `sourceos-shell.target` exists
+- the four runtime scaffold services are grouped beneath that target
+- the Nix module expresses the target and `partOf` relationships consistently
+
 ## Follow-on
 
-Once `SourceOS-Linux/sourceos-shell` exists, the placeholder ExecStart values should be replaced with real package/service paths and the current scaffold checks should be upgraded into service-graph checks.
+Once `SourceOS-Linux/sourceos-shell` exists, the placeholder ExecStart values should be replaced with real package/service paths and the current scaffold checks should be upgraded into actual runtime/service-graph checks.