fix(get): admit before the direct-iOS fast path; close the element-read outcome

Review blockers on #1877.

1. `dispatchGetViaRuntime` could complete the direct-iOS selector query before
   `resolveBoundGetRuntime`. Once `get` declares `device-runtime`, ADR 0019
   requires resolve -> admit -> bind before anything in the request path
   operates, so admission now runs first for every target shape and the fast
   path is a fast path *within* an admitted request. Regression: an eligible
   direct selector cannot operate when facts refuse admission.

2. `readTextAtPoint` returned `Promise<string>` and `readTextForNode` caught
   any throw and fell back, assigning a typed diagnostic after an untyped
   failure. It now returns a closed `ElementTextReadOutcome`; fallback happens
   only for the contract's classified reasons; unexpected errors propagate.
   The reason union is derived from its runtime list so the two cannot drift,
   and an unhandled reason is a compile error at the consumer.

This retires the generic catch the start record promised.

Author: agent

packages/contracts/src/element-text-runtime.test.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import {
+  elementTextRead,
+  type ElementTextReadOutcome,
+  type ElementTextUnreadableReason,
+} from './element-text-runtime.ts';
+
+/**
+ * The reasons this suite exercises. Kept local on purpose: exhaustiveness is enforced at the
+ * CONSUMER by `classifiedFallbackReason`'s `never` arm (a new reason is a compile error there),
+ * so a second exported runtime list would be an unconsumed parallel source of truth that could
+ * silently drift. The annotation is what ties this list back to the union.
+ */
+const UNREADABLE_REASONS: readonly ElementTextUnreadableReason[] = [
+  'no-text-at-point',
+  'surface-not-readable',
+];
+
+/**
+ * ADR 0019 §2 contract coverage for the preferred element-text read.
+ *
+ * A preferred operation may fall its consumer back to the required path only through a TYPED
+ * reason. These tests pin that the reason set is closed and exhaustively enumerated, so a new
+ * reason cannot be added without a consumer having to classify it — which is what keeps the
+ * retired generic `catch` from creeping back as "some other failure, just fall back".
+ */
+
+test('the outcome union is closed: every value is a read or a classified unreadable', () => {
+  const outcomes: readonly ElementTextReadOutcome[] = [
+    elementTextRead('live value'),
+    ...UNREADABLE_REASONS.map((reason) => ({ status: 'unreadable', reason }) as const),
+  ];
+  for (const outcome of outcomes) {
+    if (outcome.status === 'read') {
+      assert.equal(typeof outcome.text, 'string');
+      continue;
+    }
+    assert.ok(
+      (UNREADABLE_REASONS as readonly string[]).includes(outcome.reason),
+      `unreadable outcome carries an unclassified reason: ${outcome.reason}`,
+    );
+  }
+});
+
+test('a non-blank owner answer is a read that preserves the exact text', () => {
+  const outcome = elementTextRead('  padded value  ');
+  assert.deepEqual(outcome, { status: 'read', text: '  padded value  ' });
+});
+
+// Blank is a classification, not a read: an owner answering with whitespace has said there is
+// nothing at this point, and saying so by reason keeps consumers off "empty or failed?" guesswork.
+for (const [label, value] of [
+  ['empty string', ''],
+  ['whitespace', '   \n\t '],
+  ['undefined', undefined],
+  ['null', null],
+] as const) {
+  test(`a ${label} owner answer classifies as no-text-at-point`, () => {
+    assert.deepEqual(elementTextRead(value), {
+      status: 'unreadable',
+      reason: 'no-text-at-point',
+    });
+  });
+}
+
+test('read outcomes are frozen so a consumer cannot mutate a classification', () => {
+  assert.ok(Object.isFrozen(elementTextRead('value')));
+  assert.ok(Object.isFrozen(elementTextRead('')));
+});

packages/contracts/src/element-text-runtime.ts

@@ -17,14 +17,48 @@ export type ReadTextAtPointInput = Readonly<{
   execution?: ElementTextRuntimeExecution;
 }>;
 
+/**
+ * Why an owner that HAS a live read still produced no text for this point.
+ *
+ * Closed on purpose (ADR 0019 §2): a consumer may fall back to the required path only for a
+ * reason named here. Anything else — a runner transport failure, a helper crash, a bug — is an
+ * unexpected error and propagates, because silently answering from a stale captured tree after
+ * an unclassified failure is exactly the "generic catch fallback" the ADR forbids.
+ */
+export type ElementTextUnreadableReason =
+  /** The owner queried successfully and there is nothing readable at this point. */
+  | 'no-text-at-point'
+  /** The owner's read surface exists but declined this query (unsupported element/surface). */
+  | 'surface-not-readable';
+
+/** The closed outcome of one live element-text read. */
+export type ElementTextReadOutcome =
+  | Readonly<{ status: 'read'; text: string }>
+  | Readonly<{ status: 'unreadable'; reason: ElementTextUnreadableReason }>;
+
+/**
+ * Normalizes a raw owner read into the closed outcome. Blank text is not a read: an owner that
+ * answers with whitespace has told us there is nothing at this point, and saying so by reason
+ * keeps every consumer off "did it fail or is it empty?" guesswork.
+ */
+export function elementTextRead(text: string | undefined | null): ElementTextReadOutcome {
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return Object.freeze({ status: 'unreadable', reason: 'no-text-at-point' } as const);
+  }
+  return Object.freeze({ status: 'read', text } as const);
+}
+
 export type ElementTextRuntimeOperations = Readonly<{
   /**
    * The live text an owner reads at a point, which can exceed the readable text carried by an
    * already-captured snapshot node (an editable field whose value is longer than its label).
    * Declared `preferred`, never `required`: every consumer's required path answers from the
    * snapshot tree, so an owner without this operation still executes the command completely.
+   *
+   * Returns a closed typed outcome rather than a bare string, so a consumer never has to
+   * distinguish "no text here" from "the read blew up" by catching.
    */
-  readTextAtPoint(input: ReadTextAtPointInput): Promise<string>;
+  readTextAtPoint(input: ReadTextAtPointInput): Promise<ElementTextReadOutcome>;
 }>;
 
 export type ElementTextRuntimeOperationFacts = Readonly<{
@@ -43,7 +77,7 @@ export function elementTextRuntimeOperationFacts(
  * interactor-resolver seam.
  */
 export type ElementTextRuntimeHost = Readonly<{
-  readTextAtPoint(device: DeviceInfo, input: ReadTextAtPointInput): Promise<string>;
+  readTextAtPoint(device: DeviceInfo, input: ReadTextAtPointInput): Promise<ElementTextReadOutcome>;
 }>;
 
 /** Captures one selected owner's read authority for the lifetime of a request binding. */

packages/contracts/src/facades/platform.ts

@@ -263,13 +263,16 @@ export type {
 } from '../viewport-runtime.ts';
 export {
   bindElementTextRuntime,
+  elementTextRead,
   elementTextRuntimeOperationFacts,
 } from '../element-text-runtime.ts';
 export type {
+  ElementTextReadOutcome,
   ElementTextRuntimeExecution,
   ElementTextRuntimeHost,
   ElementTextRuntimeOperationFacts,
   ElementTextRuntimeOperations,
+  ElementTextUnreadableReason,
   ReadTextAtPointInput,
 } from '../element-text-runtime.ts';
 export type {

src/daemon/handlers/__tests__/interaction-get-runtime-fixture.ts

@@ -7,6 +7,7 @@ import {
   type CaptureSnapshotInput,
   type DeviceBinding,
   type PlatformRuntimeOperations,
+  type ElementTextReadOutcome,
   type ReadTextAtPointInput,
   type RuntimeFacts,
 } from '@agent-device/contracts/platform';
@@ -22,15 +23,27 @@ import { captureSnapshotWithInteractor } from '../snapshot-interactor-capture.ts
  * at `core/dispatch.ts`. The bound capture still runs the interactor capture the surrounding
  * interaction tests already mock, so only the two `get` operations are fixture-owned here.
  */
-export const mockReadTextAtPoint = vi.fn(async (_input: ReadTextAtPointInput) => '');
+export const mockReadTextAtPoint = vi.fn(
+  async (_input: ReadTextAtPointInput): Promise<ElementTextReadOutcome> =>
+    Object.freeze({ status: 'unreadable', reason: 'no-text-at-point' } as const),
+);
 
-/** Flip to model an owner whose facts advertise no live element read (web, HarmonyOS, provider). */
-export const elementReadFixtureState = { readTextAtPointAvailable: true };
+/**
+ * Flip to model an exact owner cell: no live element read (web, HarmonyOS, provider), or no
+ * capture at all (the watchOS sentinel, an inactive provider), which refuses admission outright.
+ */
+export const elementReadFixtureState = {
+  readTextAtPointAvailable: true,
+  captureSnapshotAvailable: true,
+};
 
 export function resetGetRuntimeFixture(): void {
   mockReadTextAtPoint.mockReset();
-  mockReadTextAtPoint.mockResolvedValue('');
+  mockReadTextAtPoint.mockResolvedValue(
+    Object.freeze({ status: 'unreadable', reason: 'no-text-at-point' } as const),
+  );
   elementReadFixtureState.readTextAtPointAvailable = true;
+  elementReadFixtureState.captureSnapshotAvailable = true;
 }
 
 const available = Object.freeze({ available: true } as const);
@@ -61,7 +74,7 @@ function elementReadFacts(device: DeviceInfo): RuntimeFacts<PlatformRuntimeOpera
     device: base.device,
     operations: {
       ...base.operations,
-      captureSnapshot: available,
+      captureSnapshot: elementReadFixtureState.captureSnapshotAvailable ? available : unavailable,
       readTextAtPoint: elementReadFixtureState.readTextAtPointAvailable ? available : unavailable,
     },
   });

src/daemon/handlers/__tests__/interaction-read.test.ts

@@ -1,14 +1,21 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { SnapshotNode } from '@agent-device/kernel/snapshot';
-import type { ReadTextAtPointInput } from '@agent-device/contracts/platform';
+import {
+  elementTextRead,
+  type ElementTextReadOutcome,
+  type ReadTextAtPointInput,
+} from '@agent-device/contracts/platform';
 import { readTextForNode } from '../interaction-read.ts';
 
 /**
  * Bound at the seam the handler consumes (the runtime's `readTextAtPoint` operation), never at
  * `core/dispatch.ts`: `get` is migrated, so the live read reaches this fake through the request
  * binding rather than through the legacy dispatcher.
  */
-const readTextAtPoint = vi.fn(async (_input: ReadTextAtPointInput) => 'backend-text');
+const readTextAtPoint = vi.fn(
+  async (_input: ReadTextAtPointInput): Promise<ElementTextReadOutcome> =>
+    elementTextRead('backend-text'),
+);
 
 function node(overrides: Partial<SnapshotNode>): SnapshotNode {
   return {
@@ -91,21 +98,34 @@ describe('readTextForNode', () => {
     expect(readTextAtPoint).not.toHaveBeenCalled();
   });
 
-  it('falls back to the captured tree through a typed reason when the live read fails', async () => {
-    readTextAtPoint.mockRejectedValueOnce(new Error('runner transport closed'));
+  // ADR 0019 §2: the ONLY fallbacks are the contract's classified reasons.
+  it.each(['no-text-at-point', 'surface-not-readable'] as const)(
+    'falls back to the captured tree for the classified reason %s',
+    async (reason) => {
+      readTextAtPoint.mockResolvedValueOnce({ status: 'unreadable', reason });
+      const text = await readTextForNode({
+        ...baseParams,
+        node: node({ type: 'textfield', value: 'snap' }),
+      });
+      expect(text).toBe('snap');
+    },
+  );
+
+  it('classifies a blank live read as no-text-at-point rather than reading blank text', async () => {
+    readTextAtPoint.mockResolvedValueOnce(elementTextRead('   '));
     const text = await readTextForNode({
       ...baseParams,
       node: node({ type: 'textfield', value: 'snap' }),
     });
     expect(text).toBe('snap');
   });
 
-  it('falls back to the captured tree when the live read returns blank text', async () => {
-    readTextAtPoint.mockResolvedValueOnce('   ');
-    const text = await readTextForNode({
-      ...baseParams,
-      node: node({ type: 'textfield', value: 'snap' }),
-    });
-    expect(text).toBe('snap');
+  // The retired generic catch: an unclassified failure must NOT become "this element has no
+  // text". It propagates, so a runner/helper failure can never be answered from a stale tree.
+  it('propagates an unexpected live-read failure instead of falling back', async () => {
+    readTextAtPoint.mockRejectedValueOnce(new Error('runner transport closed'));
+    await expect(
+      readTextForNode({ ...baseParams, node: node({ type: 'textfield', value: 'snap' }) }),
+    ).rejects.toThrow(/runner transport closed/);
   });
 });

src/daemon/handlers/__tests__/interaction.test.ts

@@ -58,6 +58,7 @@ vi.mock('../../../platforms/apple/core/runner/runner-client.ts', async (importOr
   };
 });
 
+import { elementTextRead } from '@agent-device/contracts/platform';
 import {
   elementReadFixtureState,
   getRuntimeBindings,
@@ -153,7 +154,9 @@ test('get text uses backend read expansion when the resolved node has a rect', a
   };
   sessionStore.set(sessionName, session);
 
-  mockReadTextAtPoint.mockResolvedValue('package com.example.app\nclass MainActivity {}');
+  mockReadTextAtPoint.mockResolvedValue(
+    elementTextRead('package com.example.app\nclass MainActivity {}'),
+  );
 
   const response = await handleInteractionCommands({
     req: {
@@ -224,6 +227,42 @@ test('get text answers from the captured tree when the bound owner advertises no
   }
 });
 
+// ADR 0019 regression: `get` declares `device-runtime`, so an ELIGIBLE direct-iOS selector —
+// one the fast path would otherwise answer without a tree capture — must not reach the device
+// until the request has resolved, admitted, and bound. A refused admission means zero runner
+// queries, not a fast-path answer that skipped exact-owner facts entirely.
+test('an eligible direct iOS selector cannot operate before admission', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'get-text-direct-before-admission';
+  sessionStore.set(sessionName, makeIosSession(sessionName, { appBundleId: 'com.example.app' }));
+  elementReadFixtureState.captureSnapshotAvailable = false;
+  mockRunAppleRunnerCommand.mockResolvedValue({
+    found: true,
+    text: 'Ada Lovelace',
+    nodes: [{ index: 0, depth: 0, type: 'StaticText', label: 'Ada Lovelace' }],
+  });
+
+  const response = await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'get',
+      positionals: ['text', 'id=name'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+    ...getRuntimeBindings(),
+  });
+
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) expect(response.error.code).toBe('UNSUPPORTED_OPERATION');
+  // The whole point: the fast path never ran.
+  expect(mockRunAppleRunnerCommand).not.toHaveBeenCalled();
+  expect(mockDispatch).not.toHaveBeenCalled();
+});
+
 test('get text simple iOS id selector uses runner query without snapshot', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'get-text-ios-direct-selector';

src/daemon/handlers/interaction-read-legacy-dispatch.ts

@@ -2,6 +2,7 @@ import { dispatchCommand } from '../../core/dispatch.ts';
 import type { SessionState } from '../types.ts';
 import type { ContextFromFlags } from './interaction-common.ts';
 import type { CommandFlags } from '@agent-device/contracts/command';
+import { elementTextRead } from '@agent-device/contracts/platform';
 import type { ReadElementTextAtPoint } from './interaction-read.ts';
 
 /**
@@ -39,6 +40,6 @@ export function legacyDispatchReadTextAtPoint(params: {
       },
     );
     const data = rawData && typeof rawData === 'object' ? rawData : undefined;
-    return typeof data?.text === 'string' ? data.text : '';
+    return elementTextRead(typeof data?.text === 'string' ? data.text : undefined);
   };
 }