workstation contract family

docs/workstation-contract-family.md

@@ -0,0 +1,56 @@
+# Workstation Contract Family
+
+This note documents the first workstation-facing contract family for SourceOS Linux developer/operator environments.
+
+## Added schemas
+
+- `schemas/LauncherAction.json`
+- `schemas/LauncherProvider.json`
+- `schemas/PackageManifest.json`
+- `schemas/DesktopProfile.json`
+- `schemas/WorkstationProfile.json`
+
+## Added examples
+
+- `examples/launcheraction.json`
+- `examples/launcherprovider.json`
+- `examples/packagemanifest.json`
+- `examples/desktopprofile.json`
+- `examples/workstationprofile.json`
+
+## Purpose
+
+These contracts promote workstation profile semantics from implementation-local YAML and shell scripts into canonical typed objects.
+
+They are intended to support:
+- reproducible workstation profile descriptions
+- launcher/action-bus interoperability
+- package layer and desktop posture reuse across repos
+- typed validation, rendering, and SDK generation downstream
+- alignment between Linux realization and the SourceOS contract layer
+
+## Boundary rule
+
+These workstation-facing types describe **what a workstation exposes and installs**.
+They do not replace execution/audit contracts already owned by the execution plane.
+
+Specifically:
+- `LauncherAction` describes a user/operator-facing action surface, not a full execution receipt.
+- `LauncherProvider` describes routing and invariants, not search index internals.
+- `PackageManifest` describes layered packages, not image-level substrate identity.
+- `DesktopProfile` describes the desktop posture, not a policy canon.
+- `WorkstationProfile` ties these together for a workstation lane while referencing—not redefining—execution/audit semantics elsewhere.
+
+## Immediate alignment target
+
+This family is intended to align with the current Linux realization in `SociOS-Linux/source-os`, including:
+- workstation-v0 package layering
+- GNOME desktop defaults and extension pinset
+- SourceOS palette / command-bus posture
+- Lampstand-backed local file search
+
+## Follow-on contract work
+
+1. Add richer search-provider and validation sub-objects once the shell/runtime product repo stabilizes.
+2. Add typed references for doctor/fix report families and runtime execution surfaces.
+3. Bind these objects into OpenAPI / AsyncAPI surfaces when the first product/runtime consumers are ready.

examples/desktopprofile.json

@@ -0,0 +1,28 @@
+{
+  "id": "urn:srcos:desktop-profile:gnome-workstation-v0",
+  "type": "DesktopProfile",
+  "specVersion": "2.1.0",
+  "desktopEnvironment": "gnome",
+  "extensionSet": [
+    "dash-to-dock@micxgx.gmail.com",
+    "appindicatorsupport@rgcjonas.gmail.com"
+  ],
+  "keybindings": [
+    {
+      "name": "SourceOS Files",
+      "binding": "<Super>e",
+      "command": "nautilus --new-window"
+    },
+    {
+      "name": "SourceOS Terminal",
+      "binding": "<Super>Return",
+      "command": "gnome-terminal"
+    }
+  ],
+  "input": {
+    "primaryBackend": "input-remapper",
+    "compatibilityBackends": ["xremap", "kinto"],
+    "gestures": "fusuma"
+  },
+  "launcherProviderRef": "urn:srcos:launcher-provider:sourceos-palette"
+}

examples/launcheraction.json

@@ -0,0 +1,14 @@
+{
+  "id": "urn:srcos:launcher-action:search-files",
+  "type": "LauncherAction",
+  "specVersion": "2.1.0",
+  "title": "Search files (Lampstand)",
+  "subtitle": "Prompt for a local file search and open the report artifact",
+  "scope": "files",
+  "command": ["sourceos", "search", "--prompt", "--snippet", "--open"],
+  "opensArtifact": true,
+  "capabilityRefs": [
+    "urn:srcos:launcher-provider:sourceos-palette",
+    "urn:srcos:workstation-profile:workstation-v0"
+  ]
+}

examples/launcherprovider.json

@@ -0,0 +1,17 @@
+{
+  "id": "urn:srcos:launcher-provider:sourceos-palette",
+  "type": "LauncherProvider",
+  "specVersion": "2.1.0",
+  "name": "SourceOS Palette",
+  "providerKind": "command-bus",
+  "trigger": "<Super>space",
+  "binary": "sourceos",
+  "scopes": {
+    "apps": "launcher",
+    "files": "linux-native-only",
+    "web": "browser-agent"
+  },
+  "invariants": [
+    "no_redundant_file_search"
+  ]
+}

examples/packagemanifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "urn:srcos:package-manifest:workstation-v0",
+  "type": "PackageManifest",
+  "specVersion": "2.1.0",
+  "name": "workstation-v0",
+  "layers": {
+    "system": {
+      "rpm_ostree": ["git", "podman", "toolbox", "wl-clipboard", "fuzzel", "input-remapper"],
+      "dnf": ["git", "podman", "toolbox", "wl-clipboard", "fuzzel", "input-remapper"]
+    },
+    "user": {
+      "brew": ["fzf", "atuin", "bat", "zoxide", "yazi", "eza", "direnv", "tmux", "lazygit", "rclone", "minio-mc", "rsync"]
+    },
+    "toolbox": {
+      "aur": ["ruby-fusuma"]
+    }
+  }
+}

examples/workstationprofile.json

@@ -0,0 +1,18 @@
+{
+  "id": "urn:srcos:workstation-profile:workstation-v0",
+  "type": "WorkstationProfile",
+  "specVersion": "2.1.0",
+  "name": "workstation-v0",
+  "channel": "linux-dev",
+  "packageManifestRef": "urn:srcos:package-manifest:workstation-v0",
+  "desktopProfileRef": "urn:srcos:desktop-profile:gnome-workstation-v0",
+  "launcherProviderRef": "urn:srcos:launcher-provider:sourceos-palette",
+  "launcherActionRefs": [
+    "urn:srcos:launcher-action:search-files"
+  ],
+  "validation": {
+    "doctorCommand": "sourceos doctor --json",
+    "statusCommand": "sourceos status --json",
+    "searchCommand": "sourceos search --snippet"
+  }
+}

schemas/DesktopProfile.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/DesktopProfile.json",
+  "title": "DesktopProfile",
+  "description": "A typed desktop-environment profile for workstation realization, including extensions, input posture, and launcher defaults.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "desktopEnvironment"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:desktop-profile:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:desktop-profile:<local-id>."
+    },
+    "type": {
+      "const": "DesktopProfile",
+      "description": "Discriminator constant — always \"DesktopProfile\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.1.0\"."
+    },
+    "desktopEnvironment": {
+      "type": "string",
+      "enum": ["gnome", "kde", "cosmic", "sway", "other"],
+      "description": "Desktop environment or shell family."
+    },
+    "extensionSet": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Pinned shell extension identifiers or package names."
+    },
+    "keybindings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "binding", "command"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "binding": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 }
+        }
+      },
+      "description": "Declarative desktop keybindings."
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primaryBackend": { "type": "string" },
+        "compatibilityBackends": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "gestures": { "type": "string" }
+      },
+      "description": "Keyboard remap and gesture posture."
+    },
+    "launcherProviderRef": {
+      "type": ["string", "null"],
+      "description": "Optional reference to the primary LauncherProvider."
+    }
+  }
+}

schemas/LauncherAction.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/LauncherAction.json",
+  "title": "LauncherAction",
+  "description": "A typed launcher or command-bus action exposed to workstation users and operators.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "title",
+    "command"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:launcher-action:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:launcher-action:<local-id>."
+    },
+    "type": {
+      "const": "LauncherAction",
+      "description": "Discriminator constant — always \"LauncherAction\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.1.0\"."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable action title."
+    },
+    "subtitle": {
+      "type": ["string", "null"],
+      "description": "Optional secondary text shown in the launcher or command palette."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["apps", "files", "web", "system", "workspace", "operator"],
+      "description": "Primary routing scope for this action."
+    },
+    "command": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Executable command vector to invoke."
+    },
+    "opensArtifact": {
+      "type": "boolean",
+      "description": "Whether this action is expected to write and/or open a local artifact for inspection."
+    },
+    "capabilityRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional references to capability, policy, or contract identifiers."
+    }
+  }
+}

schemas/LauncherProvider.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/LauncherProvider.json",
+  "title": "LauncherProvider",
+  "description": "A typed description of a workstation launcher or command-bus frontend/provider.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "name",
+    "providerKind"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:launcher-provider:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:launcher-provider:<local-id>."
+    },
+    "type": {
+      "const": "LauncherProvider",
+      "description": "Discriminator constant — always \"LauncherProvider\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. \"2.1.0\"."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable provider name."
+    },
+    "providerKind": {
+      "type": "string",
+      "enum": ["palette", "desktop-launcher", "search-provider", "command-bus"],
+      "description": "Primary provider role."
+    },
+    "trigger": {
+      "type": ["string", "null"],
+      "description": "Optional shortcut or textual trigger such as <Super>space or 'sourceos '."
+    },
+    "binary": {
+      "type": ["string", "null"],
+      "description": "Optional frontend binary or command name."
+    },
+    "scopes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "apps": { "type": "string" },
+        "files": { "type": "string" },
+        "web": { "type": "string" }
+      },
+      "description": "Routing policy for launcher scopes."
+    },
+    "invariants": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Operational invariants this provider must preserve."
+    }
+  }
+}