feat(spec): add InteractionSurface contract for keyboard-first surfaces

docs/contract-additions/command-bus.md

@@ -0,0 +1,32 @@
+# CommandBus contract addition
+
+This addition introduces `CommandBus` as the typed routing contract for keyboard-first
+cross-surface command dispatch in SourceOS / SociOS.
+
+## Why this contract exists
+
+`InteractionSurface` describes a specific user-facing surface and its ownership
+policies. What it does not describe on its own is the shared routing layer that
+interprets command prefixes, deictics, namespace handoff, and dispatch across
+multiple surfaces.
+
+`CommandBus` fills that gap by making these aspects explicit:
+
+- default interpretation (`search`, `literal-input`, `local-action`)
+- scope and explicit-command prefixes
+- dispatch ordering (`focus-owner-first`, etc.)
+- participating interaction surfaces
+- protected namespaces and host-boundary handoff policy
+
+## Intended use
+
+- canonical specification lives here in `sourceos-spec`
+- Linux / browser / shell implementations bind to this contract downstream
+- execution/control-plane repos may consume command-bus evidence later, but do not own this contract
+
+## Relationship to InteractionSurface
+
+- `InteractionSurface` = a typed surface with focus/host-boundary/command binding rules
+- `CommandBus` = the shared routing and interpretation layer that spans those surfaces
+
+Both are needed for the keyboard-navigation model, but they serve different roles.

docs/contract-additions/focus-state.md

@@ -0,0 +1,33 @@
+# FocusState contract addition
+
+This addition introduces `FocusState` as the typed ownership/state record for
+keyboard-first cross-surface interaction in SourceOS / SociOS.
+
+## Why this contract exists
+
+`InteractionSurface` describes a surface and its high-level policies.
+`CommandBus` describes routing and interpretation across multiple surfaces.
+What was still missing was an explicit typed record for **who owns the keyboard right now**.
+
+`FocusState` fills that gap by making these aspects explicit:
+
+- current surface reference
+- ownership mode (`host`, `local-surface`, `shell-overlay`, `pass-through`, etc.)
+- printable-input ownership
+- escape and tab behavior
+- completion and selection activity
+- multiline boundary-history semantics
+
+## Intended use
+
+- canonical specification lives here in `sourceos-spec`
+- Linux / browser / shell implementations bind to this state model downstream
+- execution/control-plane repos may consume focus-state evidence later, but do not own the contract
+
+## Relationship to the other keyboard-navigation contracts
+
+- `InteractionSurface` = what the surface is and what high-level policies it carries
+- `CommandBus` = how commands route across surfaces
+- `FocusState` = who owns keyboard behavior in the current moment
+
+All three are needed for the cross-surface keyboard-navigation model.

docs/contract-additions/focus-transition.md

@@ -0,0 +1,30 @@
+# FocusTransition contract addition
+
+This addition introduces `FocusTransition` as the typed transition edge between
+keyboard-focus ownership states in SourceOS / SociOS.
+
+## Why this contract exists
+
+`FocusState` describes who owns the keyboard right now. What it does not capture
+on its own is how ownership changes over time.
+
+`FocusTransition` fills that gap by making these aspects explicit:
+
+- source and destination focus states
+- transition trigger
+- priority ordering
+- whether the transition is allowed
+- conditions and ownership effect
+
+## Intended use
+
+- canonical specification lives here in `sourceos-spec`
+- Linux / browser / shell implementations bind to this transition model downstream
+- execution/control-plane repos may consume transition evidence later, but do not own the contract
+
+## Relationship to the other keyboard-navigation contracts
+
+- `InteractionSurface` = what the surface is
+- `CommandBus` = how commands route across surfaces
+- `FocusState` = who owns the keyboard right now
+- `FocusTransition` = how ownership changes from one state to another

docs/contract-additions/interaction-surface.md

@@ -0,0 +1,31 @@
+# InteractionSurface contract addition
+
+This addition introduces `InteractionSurface` as the first canonical contract for
+keyboard-first cross-surface interaction ownership in SourceOS / SociOS.
+
+## Why this contract exists
+
+Existing contract families already describe execution, policy, provenance, and
+agent-session behavior. What was missing was a typed description of the user-facing
+surface itself: launcher, browser, shell, terminal, editor, overlay, and related
+host-boundary contexts.
+
+`InteractionSurface` fills that gap by making these aspects explicit:
+
+- surface type and platform
+- focus ownership policy
+- host-boundary preservation vs mirroring vs opt-in replacement
+- command binding defaults (`/` scope, `>` explicit command mode, etc.)
+- optional command-bus / overlay / keymap references
+
+## Intended use
+
+- canonical specification lives here in `sourceos-spec`
+- Linux-side implementation may live in SourceOS / SociOS Linux repos
+- execution/control-plane repos may consume evidence or policy hooks later, but do not own this contract
+
+## Current scope
+
+This is intentionally the first slice, not the full interaction model. Follow-on
+contracts may add richer focus-state, command-bus, keymap-profile, and surface-
+discoverability types once they stabilize.

docs/contract-additions/keymap-profile.md

@@ -0,0 +1,16 @@
+# KeymapProfile contract addition
+
+`KeymapProfile` is the typed mapping profile for keyboard-first interaction in SourceOS and SociOS.
+
+It records:
+- platform and modifier strategy
+- GUI profile
+- terminal profile
+- launcher and overlay references
+- remap-engine reference
+- protected namespaces
+
+Placement rule:
+- canonical schema lives in `sourceos-spec`
+- Linux-side implementations bind to it downstream
+- donor/remap repositories may inform values but do not own the contract

examples/command_bus.json

@@ -0,0 +1,38 @@
+{
+  "id": "urn:srcos:command-bus:emvi",
+  "name": "EMVI Command Bus",
+  "description": "Cross-surface command routing for SourceOS / SociOS keyboard-first interaction across launcher, browser, shell, terminal, editor, and overlay contexts.",
+  "defaultInterpretation": "search",
+  "scopePrefix": "/",
+  "explicitCommandPrefix": ">",
+  "dispatchMode": "focus-owner-first",
+  "surfaces": [
+    "urn:srcos:interaction-surface:emvi-shell",
+    "urn:srcos:interaction-surface:shortcut-overlay",
+    "urn:srcos:interaction-surface:browser-surface",
+    "urn:srcos:interaction-surface:terminal-surface"
+  ],
+  "deictics": [
+    "current",
+    "selection",
+    "recent",
+    "here"
+  ],
+  "commandNamespaces": [
+    "browser",
+    "shell",
+    "terminal",
+    "collection",
+    "workspace"
+  ],
+  "protectedNamespaces": [
+    "terminal.pass-through",
+    "editor.insert",
+    "browser.text-field",
+    "accessibility"
+  ],
+  "handoffPolicy": "preserve-host-boundary",
+  "evidenceRefs": [
+    "urn:srcos:session:emvi-proof-slice"
+  ]
+}

examples/focus_state.json

@@ -0,0 +1,16 @@
+{
+  "id": "urn:srcos:focus-state:emvi-shell-input",
+  "surfaceRef": "urn:srcos:interaction-surface:emvi-shell",
+  "owner": "shell-overlay",
+  "mode": "input",
+  "printableInputOwner": "shell-overlay",
+  "escapeBehavior": "layered-unwind",
+  "tabBehavior": "completion-first",
+  "arrowKeyPolicy": "local-region-navigation",
+  "multilineBoundaryHistory": true,
+  "completionActive": false,
+  "selectionActive": false,
+  "evidenceRefs": [
+    "urn:srcos:session:emvi-proof-slice"
+  ]
+}

examples/focus_transition.json

@@ -0,0 +1,15 @@
+{
+  "id": "urn:srcos:focus-transition:example-1",
+  "fromStateRef": "urn:srcos:focus-state:emvi-shell-input",
+  "toStateRef": "urn:srcos:focus-state:emvi-shell-input",
+  "trigger": "escape",
+  "priority": 1,
+  "allowed": true,
+  "conditions": [
+    "completionInactive"
+  ],
+  "ownershipEffect": "retain-owner",
+  "evidenceRefs": [
+    "urn:srcos:session:emvi-proof-slice"
+  ]
+}

examples/interaction_surface.json

@@ -0,0 +1,47 @@
+{
+  "id": "urn:srcos:interaction-surface:emvi-shell",
+  "name": "EMVI Shell Surface",
+  "description": "Keyboard-first command and navigation surface spanning browser, shell, terminal, and overlay contexts while preserving host-native ownership where required.",
+  "surfaceType": "command-surface",
+  "platform": "socios-linux",
+  "modalities": [
+    "keyboard",
+    "hybrid"
+  ],
+  "focusPolicy": {
+    "owner": "shell-overlay",
+    "escapeBehavior": "layered-unwind",
+    "tabBehavior": "completion-first",
+    "multilineBoundaryHistory": true,
+    "arrowKeyPolicy": "local-region-navigation"
+  },
+  "hostBoundaryPolicy": {
+    "nativeShortcutPolicy": "preserve",
+    "passThroughInput": true,
+    "protectedNamespaces": [
+      "terminal.pass-through",
+      "editor.insert",
+      "browser.text-field",
+      "password-field",
+      "accessibility"
+    ]
+  },
+  "commandBinding": {
+    "defaultInterpretation": "search",
+    "scopePrefix": "/",
+    "explicitCommandPrefix": ">",
+    "commandBusRef": "urn:srcos:command-bus:emvi",
+    "launcherRef": null,
+    "shortcutOverlayRef": "urn:srcos:interaction-surface:shortcut-overlay",
+    "keymapProfileRef": "urn:srcos:keymap-profile:mac-linux-primary"
+  },
+  "evidenceRefs": [
+    "urn:srcos:session:emvi-proof-slice"
+  ],
+  "tags": [
+    "keyboard-nav",
+    "cross-surface",
+    "host-boundary",
+    "command-bus"
+  ]
+}

examples/keymap_profile.json

@@ -0,0 +1,30 @@
+{
+  "id": "urn:srcos:keymap-profile:mac-linux-primary",
+  "name": "Mac/Linux Primary Profile",
+  "platform": "socios-linux",
+  "primaryModifierStrategy": "mac-linux-primary",
+  "guiProfile": {
+    "physicalCtrl": "Super",
+    "physicalAlt": "Alt",
+    "physicalSuper": "Ctrl"
+  },
+  "terminalProfile": {
+    "physicalCtrl": "Ctrl",
+    "physicalAlt": "Alt",
+    "physicalSuper": "RightCtrl"
+  },
+  "launcherRefs": [],
+  "overlayRefs": [
+    "urn:srcos:interaction-surface:shortcut-overlay"
+  ],
+  "remapEngineRef": "urn:srcos:remap-engine:kinto",
+  "protectedNamespaces": [
+    "terminal.pass-through",
+    "editor.insert",
+    "browser.text-field",
+    "accessibility"
+  ],
+  "evidenceRefs": [
+    "urn:srcos:session:emvi-proof-slice"
+  ]
+}

schemas/CommandBus.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/CommandBus.json",
+  "title": "CommandBus",
+  "description": "A typed command-routing surface for keyboard-first interaction across launcher, browser, shell, terminal, editor, overlay, and workspace contexts in SourceOS / SociOS.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "defaultInterpretation",
+    "scopePrefix",
+    "explicitCommandPrefix",
+    "dispatchMode",
+    "surfaces"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:command-bus:"
+    },
+    "name": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "defaultInterpretation": {
+      "type": "string",
+      "enum": [
+        "search",
+        "literal-input",
+        "local-action"
+      ]
+    },
+    "scopePrefix": {
+      "type": "string"
+    },
+    "explicitCommandPrefix": {
+      "type": "string"
+    },
+    "dispatchMode": {
+      "type": "string",
+      "enum": [
+        "focus-owner-first",
+        "shell-overlay-first",
+        "local-surface-first"
+      ]
+    },
+    "surfaces": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^urn:srcos:interaction-surface:"
+      }
+    },
+    "deictics": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "current",
+          "selection",
+          "recent",
+          "here"
+        ]
+      }
+    },
+    "commandNamespaces": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "protectedNamespaces": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "handoffPolicy": {
+      "type": "string",
+      "enum": [
+        "preserve-host-boundary",
+        "prompt-before-handoff",
+        "policy-gated"
+      ]
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}