feat: add strict native absence assertion

Author: thymikee

docs/adr/0012-interactive-replay.md

@@ -279,14 +279,16 @@ A recorded `id` never matches a node without that id.
 >   verify against the live tree's real value at replay time, so the evidence is dropped rather than
 >   published unverified. See ADR 0017's session-scoped echo protection amendment for the mechanism.
 > - **`get` — unchanged**; already covered by the pre-dispatch path and the post-resolution guard.
-> - **`is` (all predicates except `exists`) — covered, `pre-dispatch`, the `get` pattern end-to-end.**
+> - **`is` (all predicates except `exists` and `absent`) — covered, `pre-dispatch`, the `get` pattern end-to-end.**
 >   `is` resolves a unique node immediately, so pre-action verification is semantically valid; the
 >   resolved node/tree feed record-time evidence, and dispatch threads `replayTargetGuard` into
 >   `assertExpectedResolvedTarget` exactly like `get`. The direct-iOS `is`/`wait` fast paths are gated
 >   off during recording and guarded replays, mirroring `get`'s existing recording gate.
 > - **Intentionally deferred, with tests proving no annotation is recorded and no identity check runs:**
 >   `is exists` (existence assertion with no unique winner; wait-like semantics without the
->   guard-critical role), every read-only `find` variant (fuzzy-locator resolution has no
+>   guard-critical role), `is absent` (a strict one-capture absence observation has no resolved
+>   winner; it records as an ordinary observation and its `predicate_failed` failure is always an
+>   action-failure, never an identity mismatch), every read-only `find` variant (fuzzy-locator resolution has no
 >   selector-chain identity token for the classifier, and publication already refuses mutating `find`
 >   as non-verifiable), and `wait text`/`wait stable`/duration waits/`wait @ref` (no element target, or
 >   a session-local ref that ADR 0016 already refuses to publish; `wait @ref` is rejected rather than

examples/test-app/README.md

@@ -39,7 +39,7 @@ These are the main case families this app can support without adding more screen
 - `fill` on single-line and multiline fields
 - `type` after focus for append flows
 - `get text` on headings, badges, summaries, and accordion content
-- `is visible` and `is exists` assertions
+- `is visible`, `is exists`, and `is absent` assertions
 - `wait` for async loading and success states
 - `diff snapshot` after dismissals and submits
 - long-list scrolling and `scrollintoview`

packages/contracts/package.json

@@ -239,6 +239,10 @@
       "types": "./src/interaction-error.ts",
       "default": "./src/interaction-error.ts"
     },
+    "./is-predicate": {
+      "types": "./src/is-predicate.ts",
+      "default": "./src/is-predicate.ts"
+    },
     "./interaction-guarantees": {
       "types": "./src/interaction-guarantees.ts",
       "default": "./src/interaction-guarantees.ts"

packages/contracts/src/client-selector-read.ts

@@ -7,6 +7,7 @@ import type {
 } from './client-capture.ts';
 import type { DeviceCommandBaseOptions } from './client-connection.ts';
 import type { ElementTarget } from './client-target.ts';
+import type { IsPredicate } from './is-predicate.ts';
 
 /**
  * #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only
@@ -29,15 +30,15 @@ export type GetOptions = DeviceCommandBaseOptions &
 export type IsTextPredicateOptions = DeviceCommandBaseOptions &
   SelectorSnapshotCommandOptions &
   RecordControlOptions & {
-    predicate: 'text';
+    predicate: Extract<IsPredicate, 'text'>;
     selector: string;
     value: string;
   };
 
 export type IsStatePredicateOptions = DeviceCommandBaseOptions &
   SelectorSnapshotCommandOptions &
   RecordControlOptions & {
-    predicate: 'visible' | 'hidden' | 'exists' | 'editable' | 'selected' | 'focused';
+    predicate: Exclude<IsPredicate, 'text'>;
     selector: string;
     value?: never;
   };

packages/contracts/src/interaction-error.ts

@@ -1,4 +1,5 @@
 /** Machine-readable `error.details.reason` values shared by interaction producers and adapters. */
 export const INTERACTION_ERROR_REASONS = {
   selectorNotFound: 'selector_not_found',
+  predicateFailed: 'predicate_failed',
 } as const;

packages/contracts/src/is-predicate.ts

@@ -0,0 +1,13 @@
+/** The complete predicate vocabulary accepted by the `is` command. */
+export const IS_PREDICATES = [
+  'visible',
+  'hidden',
+  'exists',
+  'absent',
+  'editable',
+  'selected',
+  'focused',
+  'text',
+] as const;
+
+export type IsPredicate = (typeof IS_PREDICATES)[number];

packages/selectors/src/index.ts

@@ -44,6 +44,7 @@ import {
 } from './internal/replay.ts';
 
 export type { FindAction, FindLocator } from './internal/find.ts';
+export { IS_PREDICATES } from '@agent-device/contracts/is-predicate';
 export type { IsPredicate } from './internal/predicates.ts';
 export type {
   PolicyResolutionOutcome,

packages/selectors/src/internal/predicates.ts

@@ -1,5 +1,6 @@
 import { refuse, type SelectorArgumentRefusal } from './argument-refusal.ts';
 
+import { IS_PREDICATES, type IsPredicate } from '@agent-device/contracts/is-predicate';
 import type { Platform, PublicPlatform } from '@agent-device/kernel/device';
 import type { SnapshotState } from '@agent-device/kernel/snapshot';
 import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
@@ -12,23 +13,15 @@ import {
 import { isNodeEditable, isNodeVisible } from './node.ts';
 import { tryParseSelectorChain } from './parse.ts';
 
-export type IsPredicate =
-  | 'visible'
-  | 'hidden'
-  | 'exists'
-  | 'editable'
-  | 'selected'
-  | 'focused'
-  | 'text';
+export type { IsPredicate } from '@agent-device/contracts/is-predicate';
 
 // Module-private since `checkIsPredicate` became the admission API: a caller that tests the
 // vocabulary without going through admission is how the case-normalization drift started.
 function isSupportedPredicate(input: string): input is IsPredicate {
-  return ['visible', 'hidden', 'exists', 'editable', 'selected', 'focused', 'text'].includes(input);
+  return (IS_PREDICATES as readonly string[]).includes(input);
 }
 
-export const IS_PREDICATE_REQUIRED_MESSAGE =
-  'is requires predicate: visible|hidden|exists|editable|selected|focused|text';
+export const IS_PREDICATE_REQUIRED_MESSAGE = `is requires predicate: ${IS_PREDICATES.join('|')}`;
 
 /**
  * The one `is` predicate admission check. Three call sites used to state this rule
@@ -67,7 +60,7 @@ export function normalizeIsPositionals(positionals: string[]): string[] {
 }
 
 export function evaluateIsPredicate(params: {
-  predicate: Exclude<IsPredicate, 'exists'>;
+  predicate: Exclude<IsPredicate, 'exists' | 'absent'>;
   node: SnapshotState['nodes'][number];
   nodes: SnapshotState['nodes'];
   expectedText?: string;
@@ -102,6 +95,8 @@ export function evaluateIsPredicate(params: {
     case 'text':
       pass = actualText === (expectedText ?? '');
       break;
+    default:
+      return assertNever(predicate);
   }
   const details =
     predicate === 'text'
@@ -115,6 +110,10 @@ export function evaluateIsPredicate(params: {
   return { pass, actualText, details };
 }
 
+function assertNever(value: never): never {
+  throw new Error(`Unhandled is predicate: ${String(value)}`);
+}
+
 function isAssertionVisible(
   node: SnapshotState['nodes'][number],
   visibility: SnapshotVisibility,

packages/selectors/src/internal/resolution-policy.ts

@@ -61,12 +61,12 @@ export const SELECTOR_RESOLUTION_POLICIES = {
     ambiguity: 'disambiguate',
     requireRect: false,
   },
-  /** `is` non-exists predicates and `get attrs` — ties reject, never guess. */
+  /** `is` predicates other than `exists`/`absent`, and `get attrs` — ties reject, never guess. */
   readUnique: {
     ambiguity: 'fail-closed',
     requireRect: false,
   },
-  /** `exists` and find's read-only actions — presence is the question. */
+  /** `exists`/`absent` and find's read-only actions — presence is the question. */
   readAny: {
     ambiguity: 'first-match',
     requireRect: false,

scripts/layering/package-boundaries.test.ts

@@ -108,6 +108,7 @@ const CONTRACT_EXPORTS = [
   '@agent-device/contracts/interactor-operation-catalog',
   '@agent-device/contracts/interactor-types',
   '@agent-device/contracts/ios-snapshot',
+  '@agent-device/contracts/is-predicate',
   '@agent-device/contracts/keyboard',
   '@agent-device/contracts/keyboard-runtime',
   '@agent-device/contracts/local-interactor-operation-set',