test(lint): pin the dispatch-contract disarm by an undeclared sibling and state it in the docblock

`collectDeclaredContracts` pools global and object-embedded actions into one
flat name namespace and counts an action that declares no `execution` as a
disagreeing declaration, so one undeclared same-named action anywhere in the
stack turns `action-dispatch-contract-mismatch` off for that name. The
behaviour is deliberate and unchanged; nothing pinned it (deleting the
`'none'` arm left the whole package green) and the docblock did not say it.

- Five tests: the lit control, an agreeing-sibling control, and the disarm
  from the view's own object, from an unrelated object and from the global
  list, each beside the same stack without the sibling.
- The docblock now states the mechanism: absence counts as disagreement,
  declarations are not scoped by the view's object, and why silence is the
  intended direction.

No logic change.

Claude-Session: https://claude.ai/code/session_013RDBh5DqXd2xnLwvHLgLFr
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/lint/src/validate-action-dispatch-contract.test.ts

@@ -207,3 +207,80 @@ describe('validateActionDispatchContract — every list tier', () => {
     expect(findings[0]!.where).toContain('object "task"');
   });
 });
+
+// ABSENCE COUNTS AS DISAGREEMENT — the disarm `collectDeclaredContracts`
+// states in its docblock. Action names are one flat namespace (global and
+// object-embedded, pooled), so ONE same-named action that declares no
+// `execution`, anywhere in the stack, turns the rule off for that name. That is
+// deliberate: zero false positives, and undeclared is not defaulted. It is
+// pinned here because nothing else holds it: with the `'none'` arm deleted,
+// every other test in this package stays green.
+//
+// A zero is a reading only when a control fires beside it, so every disarm
+// below runs the SAME stack twice: without the sibling (exactly one finding)
+// and with it (none). The agreeing-sibling control narrows the cause further:
+// a sibling that DECLARES the same contract leaves the finding standing, so it
+// is the sibling's silence that disarms the name, not its mere presence.
+describe('validateActionDispatchContract — absence counts as disagreement (the disarm)', () => {
+  type Findings = ReturnType<typeof validateActionDispatchContract>;
+
+  const RECALC_AGGREGATE = { name: 'recalc', type: 'api', execution: 'aggregate' };
+  const RECALC_UNDECLARED = { name: 'recalc', type: 'api' };
+
+  /**
+   * One view on `task`, wiring `recalc` as a bare string (the per-record
+   * contract). `invoice` is an object the view never resolves through.
+   */
+  const disarmStack = (at: {
+    global?: Record<string, unknown>[];
+    task?: Record<string, unknown>[];
+    invoice?: Record<string, unknown>[];
+  }) => ({
+    objects: [
+      { name: 'task', actions: at.task ?? [] },
+      { name: 'invoice', actions: at.invoice ?? [] },
+    ],
+    actions: at.global ?? [],
+    views: [{ name: 'task', object: 'task', list: { bulkActions: ['recalc'] } }],
+  });
+
+  const expectOneMismatch = (findings: Findings) => {
+    expect(findings).toHaveLength(1);
+    expect(findings[0]!.rule).toBe(ACTION_DISPATCH_CONTRACT_MISMATCH);
+    expect(findings[0]!.path).toBe('views[0].list.bulkActions[0]');
+  };
+
+  it('CONTROL: a global `recalc` declared `aggregate`, wired as a bare string, is refused', () => {
+    expectOneMismatch(validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE] })));
+  });
+
+  it('CONTROL: a same-named sibling that DECLARES the same contract leaves the finding standing', () => {
+    expectOneMismatch(
+      validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE], task: [RECALC_AGGREGATE] })),
+    );
+    expectOneMismatch(
+      validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE], invoice: [RECALC_AGGREGATE] })),
+    );
+  });
+
+  it("an undeclared sibling embedded in the view's own object disarms the name", () => {
+    expectOneMismatch(validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE] })));
+    expect(
+      validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE], task: [RECALC_UNDECLARED] })),
+    ).toEqual([]);
+  });
+
+  it('an undeclared sibling on an UNRELATED object disarms the name too — declarations are not scoped by the view', () => {
+    expectOneMismatch(validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE] })));
+    expect(
+      validateActionDispatchContract(disarmStack({ global: [RECALC_AGGREGATE], invoice: [RECALC_UNDECLARED] })),
+    ).toEqual([]);
+  });
+
+  it('an undeclared GLOBAL sibling disarms an object-embedded declaration', () => {
+    expectOneMismatch(validateActionDispatchContract(disarmStack({ task: [RECALC_AGGREGATE] })));
+    expect(
+      validateActionDispatchContract(disarmStack({ task: [RECALC_AGGREGATE], global: [RECALC_UNDECLARED] })),
+    ).toEqual([]);
+  });
+});

packages/lint/src/validate-action-dispatch-contract.ts

@@ -130,12 +130,36 @@ const MISFIRE: Readonly<Record<ActionDispatchContract, string>> = {
  * Every action name in the stack that DECLARES a dispatch contract, mapped to
  * the contract it declares.
  *
- * A name declared more than once (a global action and an object-embedded one,
- * or two objects) contributes only when every declaration agrees: two
- * declarations that disagree are a defect in the DECLARATIONS, not in any
- * wiring, and charging a view for it would name the wrong file. Undeclared
- * names are absent from the map, which is what makes "undeclared is not
- * defaulted" structural here rather than a branch someone can drop.
+ * Action names are ONE flat namespace here, the same one
+ * `validate-action-name-refs` resolves against: the global `actions` and every
+ * object's embedded `actions`, pooled. Each name collects the set of contracts
+ * its declarations carry, and an action that declares NO `execution` does not
+ * drop out of that set: it enters it as `'none'`. A name contributes only when
+ * its set holds exactly one member and that member is a real contract.
+ *
+ * ⇒ ABSENCE COUNTS AS DISAGREEMENT. One same-named action that declares no
+ * `execution`, anywhere in the flat namespace, turns this rule OFF for that
+ * name, for every view that wires it. "Anywhere" is literal: the view's own
+ * object, the global list, or an object the view never resolves through.
+ * Declarations are not scoped by the view's object; the map is built once for
+ * the whole stack, before any view is read.
+ *
+ * That is deliberate, and it is the zero-false-positive posture (silence is the
+ * safe direction) applied to the name rather than to the action:
+ *
+ *  - two declarations that disagree are a defect in the DECLARATIONS, not in
+ *    any wiring, and charging a view for it would name the wrong file;
+ *  - an action that declares nothing is not unanimous with one that declares
+ *    a contract, because undeclared is not defaulted to either contract.
+ *    Counting it as agreement would be exactly that silent default, arriving
+ *    through a sibling.
+ *
+ * Undeclared names are absent from the map, which is what makes "undeclared is
+ * not defaulted" structural here rather than a branch someone can drop; the
+ * `'none'` member is what carries the same rule to a name that is declared in
+ * one place and undeclared in another. The test file pins the disarm from the
+ * view's own object, from an unrelated object and from the global list, each
+ * beside a control that fires on the same stack without the sibling.
  */
 function collectDeclaredContracts(stack: AnyRec): Map<string, ActionDispatchContract> {
   const seen = new Map<string, Set<ActionDispatchContract | 'none'>>();