From c38efc021efb589eb5a23b07e2bf4268634a5027 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 16:57:04 -0400
Subject: [PATCH 1/7] runtime: add sourceos-shell command-bus search provider
 scaffold

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

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index 7ae9e9a..1be9482 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" "command-bus" "shell-native" ];
+        default = "command-bus";
+        description = "Search routing mode during shell rollout.";
+      };
+
+      linuxFileProvider = lib.mkOption {
+        type = lib.types.enum [ "lampstand" "fd" "locate" ];
+        default = "lampstand";
+        description = "Linux-native file search provider used when scope=files.";
+      };
+    };
   };
 
   config = lib.mkIf cfg.enable {
@@ -45,8 +59,25 @@ 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";
+      };
+      notes = [
+        "Lampstand is the Linux-native file authority for scope=files."
+        "The command bus remains a frontend and must not perform a second file-search pass."
+      ];
+    };
+
     systemd.services.sourceos-shell = {
       description = "SourceOS shell runtime scaffold";
       wantedBy = [ "multi-user.target" ];
@@ -73,5 +104,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 c4285a2e4affd495bca89964455d334810d81592 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 16:58:08 -0400
Subject: [PATCH 2/7] profile(linux-dev): import sourceos-shell module 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 74faf88..e7238f1 100644
--- a/profiles/linux-dev/default.nix
+++ b/profiles/linux-dev/default.nix
@@ -3,6 +3,7 @@
   imports = [
     ../../modules/build/default.nix
     ../../modules/nixos/mesh/default.nix
+    ../../modules/nixos/sourceos-shell/default.nix
   ];
 
   sourceos.build = {

From 3cd7ce8199d49cd138e8e4f6cba079167965536d Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 17:51:40 -0400
Subject: [PATCH 3/7] runtime: add command-bus search provider config

---
 linux/desktop/sourceos-search-provider.conf | 15 +++++++++++++++
 1 file changed, 15 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..b35fd7e
--- /dev/null
+++ b/linux/desktop/sourceos-search-provider.conf
@@ -0,0 +1,15 @@
+# SourceOS shell search-provider scaffold
+# This file records the intended command-bus/search routing policy during early shell rollout.
+
+mode=command-bus
+linux-file-provider=lampstand
+invariant=no_redundant_file_search
+
+# scopes
+apps=launcher
+files=linux-native-only
+web=browser-agent
+
+# notes
+# - Lampstand is the Linux-native file authority for scope=files.
+# - The command bus remains a frontend and must not perform a second file-search pass.

From 54cac9101ab94a0172863557c72b7b082a6c8c5c Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 17:53:49 -0400
Subject: [PATCH 4/7] docs(shell): add command-bus search provider note

---
 docs/sourceos-shell-command-bus.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 docs/sourceos-shell-command-bus.md

diff --git a/docs/sourceos-shell-command-bus.md b/docs/sourceos-shell-command-bus.md
new file mode 100644
index 0000000..2bfd034
--- /dev/null
+++ b/docs/sourceos-shell-command-bus.md
@@ -0,0 +1,30 @@
+# sourceos-shell command bus note
+
+During the early shell rollout, launcher/search integration is tracked as temporary command-bus 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, the command bus must not perform a second file-search pass in parallel with the Linux-native provider.
+
+Lampstand is the intended Linux-native file authority for this lane.
+
+## 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, routing invariant, and the provider choice for the Linux-native file search lane.
+
+## Lifecycle
+
+This command-bus/search-provider surface exists only until the shell's own command/search runtime fully absorbs the routing behavior.

From da4c61f931d222038bee140efa69f1ba4a246cd8 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 17:59:43 -0400
Subject: [PATCH 5/7] runtime: add sourceos-docd service 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..5cc693b
--- /dev/null
+++ b/linux/systemd/sourceos-docd.service
@@ -0,0 +1,13 @@
+[Unit]
+Description=SourceOS shell docd scaffold
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/env sh -c 'echo sourceos-docd placeholder'
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target

From 8b93f5e1f28275c58d1ce856a8811c987988e0e3 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 18:00:58 -0400
Subject: [PATCH 6/7] tests(shell): add sourceos-shell command-bus contract
 check

---
 tests/sourceos-shell-module-contract.nix | 17 +++++++++++++++++
 1 file changed, 17 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..9bd3e95
--- /dev/null
+++ b/tests/sourceos-shell-module-contract.nix
@@ -0,0 +1,17 @@
+{ 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/default.nix}
+  test -f ${../linux/desktop/sourceos-search-provider.conf}
+  test -f ${../linux/systemd/sourceos-docd.service}
+  grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/default.nix}
+  grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'searchProvider' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'lampstand' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'command-bus' ${../linux/desktop/sourceos-search-provider.conf}
+  grep -q 'no_redundant_file_search' ${../linux/desktop/sourceos-search-provider.conf}
+  mkdir -p $out
+  echo validated > $out/result.txt
+''

From b1d87809f6342030910e782014e4bb57f269e326 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Thu, 23 Apr 2026 18:01:47 -0400
Subject: [PATCH 7/7] flake: add sourceos-shell command-bus contract check

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

diff --git a/flake.nix b/flake.nix
index bc322e1..0122873 100644
--- a/flake.nix
+++ b/flake.nix
@@ -146,6 +146,7 @@
           mesh-runtime-contract = import ./tests/mesh-runtime-contract.nix { inherit pkgs; };
           mesh-package-contract = import ./tests/mesh-package-contract.nix { inherit pkgs; };
           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; };
 
           meshd-package = self.packages.${system}.meshd;
           meshd-linkd-package = self.packages.${system}.meshd-linkd;