docs: state constraints instead of narrating the refactor

Comment pass over #1656: drop the "used to be per-caller code" /
"not module constants" / "rather than an omission" narration — a comment
should say what a future edit must respect, not what the previous shape was —
and compress the find occlusion-verdict and poll-budget notes to the
constraint they actually carry.

Author: thymikee

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

@@ -32,9 +32,8 @@ import type { SelectorResolutionOptions } from './public-resolution-types.ts';
  * companion structural table, `src/core/selector-pipeline-policy.ts` (#1656),
  * whose rows each name one row of this matrix. They live there rather than
  * here because this package is deliberately blind to snapshot occlusion
- * annotations, backend visibility probes, and the wait clock; a column here
- * would be a claim nothing in this package could enforce, which is exactly the
- * unverifiable-column failure the #1649 review caught.
+ * annotations, backend visibility probes, and the wait clock: a column here
+ * would be a claim nothing in this package could enforce (#1649 review).
  */
 
 export type KnobBackedSelectorAmbiguity = 'disambiguate' | 'fail-closed' | 'first-match';

src/commands/interaction/runtime/__tests__/resolution-policy-parity.test.ts

@@ -166,9 +166,9 @@ test('rect-requiring rows skip rectless nodes; read and wait rows accept them',
  * The matrix may only declare what it can enforce (#1649 review). An earlier
  * revision carried occlusion / off-screen / promotion / poll columns that no
  * code consumed, so changing them left both behavior and the suite green —
- * an unverifiable claim reading as truth. Those four stages now live in the
+ * an unverifiable claim reading as truth. Those four stages belong to the
  * structural table (`src/core/selector-pipeline-policy.ts`, #1656), where
- * runners consume them; this still fails if such a field reappears HERE, where
+ * runners consume them; this still fails if such a field appears HERE, where
  * the selectors package has nothing to enforce it with.
  */
 test('policy rows declare only the fields this matrix actually enforces', () => {

src/commands/interaction/runtime/resolution.test.ts

@@ -603,9 +603,10 @@ test('throwIfOffscreenInteractionTarget: off-screen + backend confirms -> return
 });
 
 test('throwIfOffscreenInteractionTarget: a row whose off-screen stage is ignore returns the node untouched', async () => {
-  // #1656: reads and waits answer about the tree as captured, so the same
-  // node the acting rows refuse below passes through here — and the iOS
-  // rescue hook is never consulted, which is why it would throw if it were.
+  // #1656: reads and waits answer about the tree as captured, so the node the
+  // acting rows refuse below passes through here. The rescue hook throws on
+  // contact, so a row that started refusing would fail loudly rather than
+  // quietly spending an iOS round trip.
   const device = createInteractionDevice(makeSnapshotState([]), {
     confirmOffscreenTargetVisible: async () => {
       throw new Error('an observation row must not spend the rescue round trip');

src/commands/interaction/runtime/resolution.ts

@@ -142,9 +142,9 @@ type ResolveInteractionTargetParams = {
   requireInteractive: boolean;
   /**
    * The structural pipeline this action runs (#1656): occlusion, off-screen,
-   * and hittable-ancestor promotion are the row's decisions, not per-call-site
-   * booleans. `promotedTarget` for tap-shaped actions, `resolvedTarget` for the
-   * actions that must keep the element they resolved.
+   * and hittable-ancestor promotion are the row's decisions. `promotedTarget`
+   * for tap-shaped actions, `resolvedTarget` for the actions that must keep
+   * the element they resolved.
    */
   pipeline: ActingPipelinePolicy;
   /**
@@ -937,9 +937,8 @@ export async function preflightNativeRefInteraction(
     fallbackLabel: target.fallbackLabel ?? '',
   });
   if (!resolved) return {};
-  // `resolvedTarget`, whatever the command: this row's `none` promotion is what
-  // makes "the preflight never changes which element the backend acts on" a
-  // declared property rather than an omission at this call site.
+  // `resolvedTarget` whatever the command: its `none` promotion is what holds
+  // ADR 0011's "the preflight never changes which element the backend acts on".
   const pipeline = SELECTOR_PIPELINE_POLICIES.resolvedTarget;
   const node = resolveInteractionPipelineTarget(pipeline, nodes, resolved.node, {
     action,

src/commands/interaction/runtime/wait-polling.ts

@@ -49,9 +49,8 @@ type WaitFailurePolling = {
 
 /**
  * The poll stage of the caller's selector-pipeline row (#1656): the deadline
- * and the inter-poll delay come from the row, not from module constants, so a
- * caller cannot invent a budget and a row that resolves against a single
- * capture cannot be polled at all.
+ * and the inter-poll delay come from the row, so a caller cannot invent a
+ * budget and a row that resolves against a single capture cannot be polled.
  */
 export function createWaitPolling(
   runtime: WaitPollingRuntime,

src/core/selector-pipeline-policy.test.ts

@@ -13,12 +13,9 @@ import {
 } from './selector-pipeline-policy.ts';
 
 /**
- * #1656: the structural stages are routed through the runners below, so this
- * file is what makes the table's cells load-bearing. Every row is driven
- * through every runner — including the rows whose answer is "skip this stage",
- * which is the half that used to be invisible: `is` not consulting occlusion
- * was an absence of code, and an absence cannot fail. Flip any cell in the
- * table and an assertion here changes.
+ * #1656: every row is driven through every runner — including the rows whose
+ * answer is "skip this stage", since a skip nothing exercises is a claim that
+ * cannot fail. Flip any cell in the table and an assertion here changes.
  *
  * Which stages a given CALLER runs is a separate question, pinned by the
  * caller-level suites (resolution.test.ts, find handler tests, selector-read

src/core/selector-pipeline-policy.ts

@@ -16,18 +16,14 @@ import {
  * A caller names ONE row here and gets its whole pipeline shape: which
  * ambiguity contract resolves the selector (`resolution`, the matrix row), and
  * which structural stages run around that resolution — occlusion, off-screen,
- * hittable-ancestor promotion, and the poll budget. Those four stages used to
- * be per-caller pipeline code, so "`is` never consults occlusion" was true only
- * as an ABSENCE of code: nothing declared it and nothing could fail if a later
- * edit added it. Here it is a value, and the stage runners below are the only
- * door to each stage, so the value decides.
+ * hittable-ancestor promotion, and the poll budget. The runners below are the
+ * only door to each stage, so a row that skips one still says so as a value:
+ * making `is` consult occlusion means editing this table, not adding a call.
  *
- * Rule of this table, inherited from the #1649 review: a row may only declare
- * what these runners enforce. Every field is read by the runner named in its
- * doc comment, and every row — including the ones whose stages are skips — is
- * driven through those runners in selector-pipeline-policy.test.ts, so flipping
- * any cell changes an assertion. Do not add a column until its runner exists;
- * an unconsumed column reads as truth while being free to drift.
+ * A row may only declare what these runners enforce (#1649 review). Every row,
+ * skips included, is driven through every runner in
+ * selector-pipeline-policy.test.ts, so flipping any cell changes an assertion —
+ * add a column only once a runner reads it.
  */
 
 /**
@@ -83,9 +79,9 @@ export type SelectorPollBudget = {
 
 /**
  * Consumed by `selectorPollBudget`, which `createWaitPolling` derives its
- * deadline and sleep from. `'none'` is a real answer, not an omission: a row
- * that resolves against one capture has no polling contract, and asking for
- * its budget is a bug rather than a defaulting opportunity.
+ * deadline and sleep from. `'none'` is an answer, not an omission: a row that
+ * resolves against one capture has no polling contract, so asking for its
+ * budget is a caller bug — never a place to default one in.
  */
 export type SelectorPollStage = SelectorPollBudget | 'none';
 
@@ -203,13 +199,13 @@ export function selectorPipelineCandidates(
 
 /**
  * Stage 2, post-resolution: promotion, then the occlusion verdict on what
- * promotion produced — the order every acting caller ran by hand.
+ * promotion produced.
  *
- * `occluded` carries the node to NAME in the refusal, which is the promotion
- * input when the match itself is covered (promotion declines to retarget away
- * from a covered node) and the promotion output otherwise. The refusal shape
- * stays with the caller: the same verdict is a thrown interaction error, a
- * daemon response, or a diagnosis, and those are not interchangeable.
+ * `occluded` carries the node to NAME in the refusal — the promotion input
+ * when the match itself is covered (promotion declines to retarget away from a
+ * covered node), the promotion output otherwise. The refusal SHAPE stays with
+ * the caller: this verdict becomes a thrown interaction error, a daemon
+ * response, or a diagnosis, and those are not interchangeable.
  */
 export type SelectorPipelineTarget =
   | { kind: 'target'; node: SnapshotNode }

src/daemon/handlers/find.ts

@@ -77,11 +77,9 @@ type ResolvedMatch = {
   nodes: SnapshotState['nodes'];
   actionFlags: Record<string, unknown>;
   /**
-   * The occlusion verdict the `findAct` row produced for this match, carried
-   * rather than raised: `find click`/`fill` re-enter the interaction leaf,
-   * which refuses covered targets in the acting row's own error shape, so only
-   * the focus/type seam — which dispatches to the device directly — surfaces
-   * it here.
+   * Set when find's row refuses this match as covered. Only the focus/type
+   * seam surfaces it: click/fill re-enter the interaction leaf, which owns
+   * that refusal's shape and raises it against the same node.
    */
   occludedNode?: SnapshotState['nodes'][number];
 };
@@ -288,9 +286,8 @@ function resolveFindMatch(params: {
 }): FindMatchResult {
   const { nodes, locator, query, selectorExpression, flags, platform } = params;
   const pipeline = SELECTOR_PIPELINE_POLICIES.findAct;
-  // The occlusion stage of find's row: it declares `refuse`, so covered nodes
-  // stay candidates here (find ranks and reports them) and are refused later,
-  // at the target. Acting rows exclude them from candidacy instead.
+  // The occlusion stage of find's row: `refuse` keeps covered nodes as
+  // candidates here — find ranks and reports them — and refuses at the target.
   const searchableNodes = selectorPipelineCandidates(
     pipeline,
     nodes.filter((node) => !isRootInteractionContainer(node, nodes[0])),