taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/assets/skills/{taphound-ai-journey → taphound-journey-generator}/schemas/proposed-step-envelope.json

@@ -2,10 +2,14 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://taphound.dev/schemas/proposed-step-envelope.json",
   "title": "TapHound Proposed Step Envelope",
-  "description": "The input envelope for `generation step --input`. The proposal field is a ProposedStep; the snapshot field is the full RuntimeSnapshot from the preceding observe call.",
+  "description": "The input envelope for `generation step --input`. The proposal field is a ProposedStep. The snapshot context may be provided either inline (snapshot: the full RuntimeSnapshot from the preceding observe call) or by reference (snapshotRef: the snapshotRef string emitted by that observe call). Exactly one of snapshot or snapshotRef must be present. The `bridge` action is NOT submitted via this envelope; it is handled by the separate `generation bridge` CLI command which builds the proposal internally.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "proposal", "snapshot"],
+  "required": ["version", "proposal"],
+  "oneOf": [
+    { "required": ["snapshot"] },
+    { "required": ["snapshotRef"] }
+  ],
   "properties": {
     "version": { "const": 1 },
     "proposal": {
@@ -13,6 +17,11 @@
     },
     "snapshot": {
       "$ref": "#/$defs/RuntimeSnapshot"
+    },
+    "snapshotRef": {
+      "type": "string",
+      "pattern": "^\\.taphound/build/generations/(?:\\.[^/]+\\.work|[^/]+)/evidence/snapshots/revision-\\d+/[^/]+/snapshot\\.json$",
+      "description": "Store-owned evidence reference returned as snapshotRef (observe) or nextSnapshotRef (step) output. Must reference the same generation session as proposal.binding.generationId."
     }
   },
   "$defs": {
@@ -28,20 +37,49 @@
       "type": "string",
       "pattern": "^[A-Za-z\\d](?:[A-Za-z\\d._-]*[A-Za-z\\d])?$"
     },
+    "LocatorEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "semanticSha256"],
+      "properties": {
+        "version": { "const": 1 },
+        "semanticSha256": { "$ref": "#/$defs/Sha256" }
+      },
+      "description": "Core-owned non-geometric semantic evidence for the element selected by index."
+    },
     "Locator": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "resourceId": { "type": "string", "minLength": 1 },
         "text": { "type": "string", "minLength": 1 },
-        "contentDescription": { "type": "string", "minLength": 1 }
+        "contentDescription": { "type": "string", "minLength": 1 },
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Zero-based ordinal applied after all identity fields have narrowed the candidate set."
+        },
+        "within": {
+          "$ref": "#/$defs/Locator",
+          "description": "Optional deterministic ancestor scope. Only descendants of this Locator participate in target matching."
+        },
+        "evidence": {
+          "$ref": "#/$defs/LocatorEvidence",
+          "description": "Optional Core-owned evidence. Callers normally omit it; Core adds it when persisting a resolvable indexed step."
+        }
       },
       "anyOf": [
         { "required": ["resourceId"] },
         { "required": ["text"] },
         { "required": ["contentDescription"] }
       ],
-      "description": "At least one identity field is required. Priority: resourceId > text > contentDescription."
+      "allOf": [
+        {
+          "if": { "required": ["evidence"] },
+          "then": { "required": ["index"] }
+        }
+      ],
+      "description": "At least one identity field is required. Priority: resourceId > text > contentDescription. Use within for a stable ancestor scope, then index only when identical candidates remain."
     },
     "ProposalBinding": {
       "type": "object",
@@ -81,8 +119,27 @@
           "properties": {
             "type": { "const": "element" },
             "locator": { "$ref": "#/$defs/Locator" },
+            "enabled": { "type": "boolean" },
+            "clickable": { "type": "boolean" },
+            "absent": { "type": "boolean" },
             "timeoutMs": { "type": "integer", "minimum": 1 }
-          }
+          },
+          "allOf": [
+            {
+              "if": {
+                "properties": { "absent": { "const": true } },
+                "required": ["absent"]
+              },
+              "then": {
+                "not": {
+                  "anyOf": [
+                    { "required": ["enabled"] },
+                    { "required": ["clickable"] }
+                  ]
+                }
+              }
+            }
+          ]
         },
         {
           "type": "object",
@@ -220,6 +277,7 @@
       "required": ["id", "enabled", "children"],
       "properties": {
         "id": { "type": "string", "minLength": 1 },
+        "windowId": { "type": "string", "minLength": 1 },
         "resourceId": { "type": "string", "minLength": 1 },
         "text": { "type": "string" },
         "contentDescription": { "type": "string" },
@@ -260,6 +318,70 @@
         "layout": {
           "type": "array",
           "items": { "$ref": "#/$defs/LayoutElement" }
+        },
+        "windowHierarchy": {
+          "$ref": "#/$defs/WindowHierarchy"
+        }
+      }
+    },
+    "AppWindow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "packageName", "touchable"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "packageName": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "minLength": 1 },
+        "layer": { "type": "integer", "minimum": 0 },
+        "bounds": { "$ref": "#/$defs/Bounds" },
+        "touchable": { "type": "boolean" },
+        "focusable": { "type": "boolean" },
+        "focused": { "type": "boolean" }
+      }
+    },
+    "WindowHierarchy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "appWindows", "semanticWindowIds", "diagnostics", "recovery"],
+      "properties": {
+        "status": { "enum": ["complete", "incomplete", "unknown"] },
+        "appWindows": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/AppWindow" }
+        },
+        "semanticWindowIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "message"],
+            "properties": {
+              "code": {
+                "enum": [
+                  "WINDOW_TOPOLOGY_UNAVAILABLE",
+                  "SEMANTIC_WINDOW_IDS_UNAVAILABLE",
+                  "APP_WINDOW_WITHOUT_SEMANTIC_ROOT",
+                  "APP_WINDOW_NOT_ACCESSIBILITY_READABLE"
+                ]
+              },
+              "message": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "recovery": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "REOBSERVE",
+              "LAYOUT_INSPECTOR",
+              "DEBUG_WINDOW_INSPECTOR"
+            ]
+          }
         }
       }
     }