runtime contract enforcement

docs/runtime-output.md

@@ -0,0 +1,178 @@
+# Runtime Output Contract
+
+This document defines the current output contract for `deskctl`.
+
+It is intentionally scoped to the current Linux X11 runtime surface.
+It does not promise stability for future Wayland or window-manager-specific features.
+
+## Goals
+
+- Keep `deskctl` fully non-interactive
+- Make text output actionable for quick terminal and agent loops
+- Make `--json` safe for agent consumption without depending on incidental formatting
+
+## JSON Envelope
+
+Every runtime command uses the same top-level JSON envelope:
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null
+}
+```
+
+Stable top-level fields:
+
+- `success`
+- `data`
+- `error`
+
+`success` is always the authoritative success/failure bit.
+When `success` is `false`, the CLI exits non-zero in both text mode and `--json` mode.
+
+## Stable Fields
+
+These fields are stable for agent consumption in the current Phase 1 runtime contract.
+
+### Window Identity
+
+Whenever a runtime response includes a window payload, these fields are stable:
+
+- `ref_id`
+- `window_id`
+- `title`
+- `app_name`
+- `x`
+- `y`
+- `width`
+- `height`
+- `focused`
+- `minimized`
+
+`window_id` is the stable public identifier for a live daemon session.
+`ref_id` is a short-lived convenience handle for the current window snapshot/ref map.
+
+### Grouped Reads
+
+`deskctl get active-window`
+
+- stable: `data.window`
+
+`deskctl get monitors`
+
+- stable: `data.count`
+- stable: `data.monitors`
+- stable per monitor:
+  - `name`
+  - `x`
+  - `y`
+  - `width`
+  - `height`
+  - `width_mm`
+  - `height_mm`
+  - `primary`
+  - `automatic`
+
+`deskctl get version`
+
+- stable: `data.version`
+- stable: `data.backend`
+
+`deskctl get systeminfo`
+
+- stable: `data.backend`
+- stable: `data.display`
+- stable: `data.session_type`
+- stable: `data.session`
+- stable: `data.socket_path`
+- stable: `data.screen`
+- stable: `data.monitor_count`
+- stable: `data.monitors`
+
+### Waits
+
+`deskctl wait window`
+`deskctl wait focus`
+
+- stable: `data.wait`
+- stable: `data.selector`
+- stable: `data.elapsed_ms`
+- stable: `data.window`
+
+### Selector-Driven Action Success
+
+For selector-driven action commands that resolve a window target, these identifiers are stable when present:
+
+- `data.ref_id`
+- `data.window_id`
+- `data.title`
+- `data.selector`
+
+This applies to:
+
+- `click`
+- `dblclick`
+- `focus`
+- `close`
+- `move-window`
+- `resize-window`
+
+The exact human-readable text rendering of those commands is not part of the JSON contract.
+
+### Artifact-Producing Commands
+
+`snapshot`
+`screenshot`
+
+- stable: `data.screenshot`
+
+When the command also returns windows, `data.windows` uses the stable window payload documented above.
+
+## Stable Structured Error Kinds
+
+When a runtime command returns structured JSON failure data, these error kinds are stable:
+
+- `selector_not_found`
+- `selector_ambiguous`
+- `selector_invalid`
+- `timeout`
+- `not_found`
+- `window_not_focused` as `data.last_observation.kind` or equivalent observation payload
+
+Stable structured failure fields include:
+
+- `data.kind`
+- `data.selector` when selector-related
+- `data.mode` when selector-related
+- `data.candidates` for ambiguous selector failures
+- `data.message` for invalid selector failures
+- `data.wait`
+- `data.timeout_ms`
+- `data.poll_ms`
+- `data.last_observation`
+
+## Best-Effort Fields
+
+These values are useful but environment-dependent and should be treated as best-effort:
+
+- exact monitor naming conventions
+- EWMH/window-manager-dependent window ordering details
+- cosmetic text formatting in non-JSON mode
+- screenshot file names when the caller did not provide an explicit path
+- command stderr wording outside the structured `kind` classifications above
+
+## Text Mode Expectations
+
+Text mode is intended to stay compact and follow-up-useful.
+
+The exact whitespace/alignment of text output is not stable.
+The following expectations are stable at the behavioral level:
+
+- important runtime reads print actionable identifiers or geometry
+- selector failures print enough detail to recover without `--json`
+- artifact-producing commands print the artifact path
+- window listings print both `@wN` refs and `window_id` values
+
+If an agent needs strict parsing, it should use `--json`.