fix(cues.fire): default auto_verify=False until substrate echo semantics locked

CI revealed: substrate's /v1/cues/{id}/fire echoes a pydantic-after-parse
body that includes server-side default-population (e.g. empty {} request
gets echoed as 16-byte populated-defaults JSON). Client's canonical-JSON
serialization diverges from substrate's defaulted echo → spurious
BodyVerifyMismatchError on integration tests.

Mitigation: default auto_verify=False on CuesResource.fire. Callers opt-
in via auto_verify=True when their serialization aligns with substrate's
echo semantic. Once cueapi-primary locks per-field echo semantics for
fire (sibling to the body_received semantic locked for /v1/messages),
flip default to True.

Existing fire tests reverted to expect headers={} (no auto-verify).
TestFireAutoVerify class tests updated to explicitly pass auto_verify=True.

39 of 39 messages + cues resource tests pass. Integration tests in
test_cues.py no longer raise spurious BodyVerifyMismatchError.

Author: mikemolinet

CHANGELOG.md

@@ -6,7 +6,7 @@ All notable changes to cueapi-sdk will be documented here.
 
 ### Added
 
-- **`client.cues.fire(auto_verify=True)` body-verify mirror (Mike body-verify directive 2026-05-11).** Parallel to `MessagesResource.send` auto_verify. Default verify-on. Sends `X-CueAPI-Verify-Echo: true` request header; substrate echoes received body bytes under `body_received` (str) + SHA256 hex under `body_received_sha256`. SDK computes sha256 of canonical request body + compares hex equality (constant-cost verify path), falling back to full string compare on hash mismatch. On drift raises `BodyVerifyMismatchError` with diagnostic attributes including `message_id` (= execution_id for fire). `auto_verify=False` opts out. Backward-compat: pre-Layer-1 substrate omits the echo fields → no-op + success. Defensive isinstance handles both dict (pre-substrate-fix) and string (post-fix 2026-05-11 ~23:48Z) wire shapes.
+- **`client.cues.fire(auto_verify=False)` body-verify mirror — OPT-IN (Mike body-verify directive 2026-05-11).** Parallel to `MessagesResource.send(auto_verify=True)`. Default OFF for cues fire because substrate's `/v1/cues/{id}/fire` echoes a pydantic-after-parse body that may include server-side default-population (verified empirically against staging CI ~23:48Z); diffing client's canonical-JSON vs substrate's parsed-defaulted echo would cause spurious mismatch. Callers can opt-in via `auto_verify=True` when they know substrate echo semantics match client serialization (typical for sha256-based constant-cost path). Implementation includes sha256 hex compare (constant-cost) with string-compare fallback on hash drift. On confirmed drift raises `BodyVerifyMismatchError` with diagnostic attributes including `message_id` (= execution_id for fire). Defensive isinstance handles both dict (pre-substrate-fix) and string (post-fix 2026-05-11 ~23:48Z) wire shapes. When cueapi-primary locks per-field echo semantics for fire, default will flip to True.
 - **`client.messages.send(auto_verify=True)` body-verify defense (Mike directive 2026-05-11).** New `auto_verify` kwarg, default `True`. When set, the SDK sends `X-CueAPI-Verify-Echo: true` request header. Substrate-side (Phase 1; cueapi-core's lane) echoes the body it received back in the response under `body_received`. SDK diffs sent vs received and raises `BodyVerifyMismatchError` on drift (with `sent_body`, `received_body`, `first_divergence_byte`, `message_id` attributes for programmatic recovery / diagnostic output). Catches the caller-side shell-expansion bug class where `body=f"... {dynamic_var} ..."` or worse `body=os.popen(...)` silently mutated body content upstream. Opt-out via `auto_verify=False` for perf-sensitive flows. Backward-compat: SDK no-ops when substrate omits the echo field (pre-Layer-1 behavior unchanged). New helper: `cueapi.exceptions.first_divergence_byte(a, b)` returns the byte index of the first differing position (pure function; re-usable cross-SDK).
 - `client.cues.bulk_delete(ids)` — delete up to 100 cues in a single call. Returns `{"deleted": [...], "skipped": [...]}`. Per-ID atomic, not batch atomic. Sends `X-Confirm-Destructive: true` header automatically. Wraps `POST /v1/cues/bulk-delete` (cueapi #650). Parity port of cueapi-cli #46. Raises `ValueError` client-side on empty list or > 100 IDs.
 

cueapi/resources/cues.py

@@ -285,7 +285,7 @@ def fire(
         send_at: Optional[Union[str, datetime]] = None,
         exit_criteria: Optional[List[str]] = None,
         idempotency_key: Optional[str] = None,
-        auto_verify: bool = True,
+        auto_verify: bool = False,
     ) -> Dict[str, Any]:
         """Fire an existing cue, optionally overriding payload + scheduling.
 

tests/test_cues_resource.py

@@ -6,11 +6,12 @@
 
 
 class TestFire:
-    """Default ``auto_verify=True`` adds X-CueAPI-Verify-Echo header on every
-    call (Phase 2 of body-verify defense in depth; Mike directive 2026-05-11).
-    TestFireAutoVerify class below pins the verify behavior explicitly."""
-
-    _VERIFY_HEADER = {"X-CueAPI-Verify-Echo": "true"}
+    """Default ``auto_verify=False`` for ``CuesResource.fire`` — substrate's
+    /v1/cues/{id}/fire echoes a pydantic-after-parse body that may include
+    server-side default-population, causing spurious diff vs caller's
+    canonical-JSON serialization. Until field-by-field echo semantic is
+    locked with cueapi-primary, fire's auto_verify is opt-in via explicit
+    kwarg. TestFireAutoVerify class below pins the opt-in verify behavior."""
 
     def test_fire_no_payload_override(self):
         mock_client = MagicMock()
@@ -20,7 +21,7 @@ def test_fire_no_payload_override(self):
         result = resource.fire("cue_abc123")
 
         mock_client._post.assert_called_once_with(
-            "/v1/cues/cue_abc123/fire", json={}, headers=self._VERIFY_HEADER,
+            "/v1/cues/cue_abc123/fire", json={}, headers={},
         )
         assert result["id"] == "exec_test"
 
@@ -35,7 +36,7 @@ def test_fire_with_payload_override_only(self):
         mock_client._post.assert_called_once_with(
             "/v1/cues/cue_abc123/fire",
             json={"payload_override": payload},
-            headers=self._VERIFY_HEADER,
+            headers={},
         )
 
     def test_fire_with_payload_override_and_merge_strategy(self):
@@ -49,7 +50,7 @@ def test_fire_with_payload_override_and_merge_strategy(self):
         mock_client._post.assert_called_once_with(
             "/v1/cues/cue_abc123/fire",
             json={"payload_override": payload, "merge_strategy": "replace"},
-            headers=self._VERIFY_HEADER,
+            headers={},
         )
 
 
@@ -61,29 +62,33 @@ class TestFireAutoVerify:
     SDK compares + raises BodyVerifyMismatchError on drift.
     """
 
-    def test_default_adds_verify_echo_header(self):
+    def test_default_off_omits_verify_echo_header(self):
+        """auto_verify defaults to False on fire (substrate echo semantics
+        not yet locked for /v1/cues/{id}/fire; opt-in until field-by-field
+        semantic confirmed with cueapi-primary)."""
         mock_client = MagicMock()
         mock_client._post.return_value = {"id": "exec_x"}
         resource = CuesResource(mock_client)
 
         resource.fire("cue_abc")
 
         headers = mock_client._post.call_args.kwargs.get("headers", {})
-        assert headers.get("X-CueAPI-Verify-Echo") == "true"
+        assert "X-CueAPI-Verify-Echo" not in headers
 
-    def test_opt_out_omits_header(self):
+    def test_opt_in_adds_verify_echo_header(self):
         mock_client = MagicMock()
         mock_client._post.return_value = {"id": "exec_x"}
         resource = CuesResource(mock_client)
 
-        resource.fire("cue_abc", auto_verify=False)
+        resource.fire("cue_abc", auto_verify=True)
 
         headers = mock_client._post.call_args.kwargs.get("headers", {})
-        assert "X-CueAPI-Verify-Echo" not in headers
+        assert headers.get("X-CueAPI-Verify-Echo") == "true"
 
     def test_byte_identical_sha256_passes(self):
         """When server's body_received_sha256 matches client's computed
-        sha256, send() returns response normally (constant-cost path)."""
+        sha256, send() returns response normally (constant-cost path).
+        Requires explicit auto_verify=True since fire defaults to off."""
         import hashlib
         import json
         # Compute expected sha256 of the canonical request body
@@ -99,30 +104,34 @@ def test_byte_identical_sha256_passes(self):
         }
         resource = CuesResource(mock_client)
 
-        result = resource.fire("cue_abc", payload_override={"task": "test"})
+        result = resource.fire(
+            "cue_abc", payload_override={"task": "test"}, auto_verify=True
+        )
 
         assert result["id"] == "exec_x"
 
     def test_no_op_when_substrate_omits_echo_field(self):
-        """Pre-Layer-1 substrate omits body_received → no raise."""
+        """Pre-Layer-1 substrate (or default-off path) omits echo → no raise."""
         mock_client = MagicMock()
         mock_client._post.return_value = {"id": "exec_x"}
         resource = CuesResource(mock_client)
 
-        result = resource.fire("cue_abc")
+        result = resource.fire("cue_abc", auto_verify=True)
 
         assert result["id"] == "exec_x"
 
-    def test_opt_out_skips_verify_even_if_substrate_echoes(self):
-        """auto_verify=False: even if substrate sends body_received, don't check."""
+    def test_default_off_skips_verify_even_if_substrate_echoes(self):
+        """Default auto_verify=False: even if substrate sends body_received
+        (e.g. caller targets a different SDK that opted in), this call
+        doesn't check. Pins the default-off invariant."""
         mock_client = MagicMock()
         mock_client._post.return_value = {
             "id": "exec_x",
             "body_received": "completely different body",
         }
         resource = CuesResource(mock_client)
 
-        result = resource.fire("cue_abc", auto_verify=False)
+        result = resource.fire("cue_abc")  # default auto_verify=False
 
         assert result["id"] == "exec_x"