From e5ab92fc8e0ad622a431670a4e24ec92680959c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Sat, 4 Jul 2026 17:17:49 +0200
Subject: [PATCH] docs: record that the native-ref path is web-only in
 production

tapTarget/fillTarget are wired solely to the web provider's clickRef
(interaction-runtime.ts); apple/android backends never define them.
Found while designing the #1088 retirement experiment, which this
dissolves: the hypothesized iOS runner round trip does not exist.
---
 src/contracts/interaction-guarantees.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/contracts/interaction-guarantees.ts b/src/contracts/interaction-guarantees.ts
index 3770a4baf..4cce8f3c2 100644
--- a/src/contracts/interaction-guarantees.ts
+++ b/src/contracts/interaction-guarantees.ts
@@ -251,8 +251,13 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
     },
   },
   'native-ref': {
+    // WEB-ONLY in production: apple/android backends never define
+    // tapTarget/fillTarget - the sole wiring is the web provider's clickRef
+    // (a stable DOM-handle click). Verified 2026-07-04 while designing the
+    // #1088 retirement experiment, which this finding dissolved: there is no
+    // iOS runner round trip to retire.
     description:
-      'click @ref / fill @ref dispatch to backend.tapTarget/fillTarget without runtime resolution when no non-default options are set. A zero-round-trip preflight (preflightNativeRefInteraction) runs the shared guards against the stored session snapshot node first; no snapshot / no usable rect makes the preflight a no-op.',
+      'click @ref / fill @ref dispatch to backend.tapTarget/fillTarget (web provider clickRef only; no mobile backend implements these) without runtime resolution when no non-default options are set. A zero-round-trip preflight (preflightNativeRefInteraction) runs the shared guards against the stored session snapshot node first; no snapshot / no usable rect makes the preflight a no-op.',
     commands: ['click', 'fill'],
     guarantees: {
       disambiguation: {