refactor(contracts): make keyboard capability facts additive (#2459)

The keyboard family's facts builder took one required cell per operation, so an
operation only one owner implements still cost a hand-written denial in every
other owner. The builder now takes the family's denial once, as `unsupported`,
and every operation cell is optional: an owner names what it serves and omission
reports that denial verbatim, with the reason and hint the owner would otherwise
have repeated per cell.

Omission stays a classified refusal, never an unclassified cell and never an
implied success: `unsupported` is required, so a call that leaves the family
blank does not compile. An owner that names every operation still states the
family refusal, and it must refuse the family rather than one operation of it —
whatever the owner leaves unnamed reports that cell verbatim.

The shared unavailable-facts input collapses `keyboardStatus`/`keyboardDismiss`/
`keyboardEnter` into one required `keyboard` cell, so the owners that answered
the family with raw keys (webdriver, vega, linux, limrun's no-session binding)
now answer it through the builder, which is the family's one entry point.

Facts are unchanged for every owner, so the per-platform admission assertions
hold untouched. Two owner tests now assert the keyboard reason as well as the
availability, because one family cell reports one reason for all three
operations: the WebDriver inactive session and the stale Limrun identity.

Refs #2443

Author: thymikee

packages/contracts/src/keyboard-runtime.test.ts

@@ -17,20 +17,58 @@ const device = {
 const local = (resolveInteractor: LocalInteractorOperationResolver) =>
   localInteractorSource({ device, resolveInteractor });
 
-test('builds the exact keyboard operation fact catalog', () => {
+const available = { available: true } as const;
+
+test('builds the exact keyboard operation fact catalog for an owner that names every operation', () => {
+  const familyDenial = {
+    available: false,
+    reason: 'unsupported-device-kind',
+  } as const;
   const status = { available: true } as const;
   const dismiss = {
     available: false,
     reason: 'unsupported-platform-leaf',
   } as const;
   const enter = { available: true } as const;
-  expect(keyboardRuntimeOperationFacts({ status, dismiss, enter })).toEqual({
+  expect(
+    keyboardRuntimeOperationFacts({ unsupported: familyDenial, status, dismiss, enter }),
+  ).toEqual({
     keyboardStatus: status,
     keyboardDismiss: dismiss,
     keyboardEnter: enter,
   });
 });
 
+test('an operation the owner never names reports the denial the owner stated for the family, verbatim — omission is a classified refusal, never an unclassified cell and never an implied success', () => {
+  const denial = {
+    available: false,
+    reason: 'unsupported-platform-leaf',
+    hint: 'Limrun iOS direct sessions do not expose keyboard actions.',
+  } as const;
+
+  expect(keyboardRuntimeOperationFacts({ unsupported: denial, dismiss: available })).toEqual({
+    keyboardStatus: denial,
+    keyboardDismiss: available,
+    keyboardEnter: denial,
+  });
+});
+
+test('an owner serving no keyboard operation names the family denial once and still answers with the exhaustive shape', () => {
+  const denial = {
+    available: false,
+    reason: 'unsupported-platform-leaf',
+  } as const;
+
+  const facts = keyboardRuntimeOperationFacts({ unsupported: denial });
+
+  expect(facts).toEqual({
+    keyboardStatus: denial,
+    keyboardDismiss: denial,
+    keyboardEnter: denial,
+  });
+  expect(Object.isFrozen(facts)).toBe(true);
+});
+
 test('a local status binding drives the interactor and returns its report', async () => {
   const keyboardStatus = vi.fn(async () => ({ visible: true }));
   const resolveInteractor = vi.fn(async () => ({ keyboardStatus }) as unknown as Interactor);

packages/contracts/src/keyboard-runtime.ts

@@ -6,7 +6,7 @@ import type {
   KeyboardStatusResult,
   RunnerContext,
 } from './interactor-types.ts';
-import type { RuntimeOperationFact } from './platform-runtime.ts';
+import type { RuntimeOperationFact, RuntimeOperationUnavailability } from './platform-runtime.ts';
 import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
 
 export type { KeyboardDismissResult, KeyboardEnterResult, KeyboardStatusResult };
@@ -43,17 +43,35 @@ export type KeyboardRuntimeOperationFacts = Readonly<{
   keyboardEnter: RuntimeOperationFact;
 }>;
 
+/**
+ * What an owner declares about the keyboard family. No operation here is one every owner serves,
+ * and several owners serve no keyboard operation at all, so every operation is optional and
+ * `unsupported` names the denial an omitted cell reports. An owner with no keyboard surface states
+ * that denial once instead of writing it out per operation, with the reason and hint it would
+ * otherwise repeat by hand.
+ *
+ * Omission is a classified denial, never an unclassified cell and never an implied success: the
+ * type refuses a call that does not carry `unsupported`, so no owner can leave the family blank.
+ * An owner that serves one operation names it — omission means "refuses", never "the same as the
+ * neighbour" — and its `unsupported` must refuse the family, not one operation of it, because
+ * whatever the owner leaves unnamed reports that cell verbatim.
+ */
+export type KeyboardRuntimeOperationFactsInput = Readonly<{
+  unsupported: RuntimeOperationUnavailability;
+  status?: RuntimeOperationFact;
+  dismiss?: RuntimeOperationFact;
+  enter?: RuntimeOperationFact;
+}>;
+
 export function keyboardRuntimeOperationFacts(
-  input: Readonly<{
-    status: RuntimeOperationFact;
-    dismiss: RuntimeOperationFact;
-    enter: RuntimeOperationFact;
-  }>,
+  input: KeyboardRuntimeOperationFactsInput,
 ): KeyboardRuntimeOperationFacts {
+  const declared = (fact: RuntimeOperationFact | undefined): RuntimeOperationFact =>
+    fact ?? input.unsupported;
   return Object.freeze({
-    keyboardStatus: input.status,
-    keyboardDismiss: input.dismiss,
-    keyboardEnter: input.enter,
+    keyboardStatus: declared(input.status),
+    keyboardDismiss: declared(input.dismiss),
+    keyboardEnter: declared(input.enter),
   });
 }
 

packages/contracts/src/platform-runtime-unavailable.test.ts

@@ -47,9 +47,7 @@ const UNAVAILABLE_FACTS: UnavailablePlatformRuntimeFacts = {
   home: { available: false, reason: 'unsupported-provider-mode' },
   orientation: { available: false, reason: 'unsupported-provider-mode' },
   tvRemote: { available: false, reason: 'unsupported-provider-mode' },
-  keyboardStatus: { available: false, reason: 'unsupported-provider-mode' },
-  keyboardDismiss: { available: false, reason: 'unsupported-provider-mode' },
-  keyboardEnter: { available: false, reason: 'unsupported-provider-mode' },
+  keyboard: { available: false, reason: 'unsupported-provider-mode' },
   readClipboard: { available: false, reason: 'unsupported-provider-mode' },
   writeClipboard: { available: false, reason: 'unsupported-provider-mode' },
   appSwitcher: { available: false, reason: 'unsupported-provider-mode' },
@@ -92,6 +90,12 @@ test('generic unavailable binding preserves exact provider ownership and mode',
     available: false,
     reason: 'unsupported-provider-mode',
   });
+  for (const operation of ['keyboardStatus', 'keyboardDismiss', 'keyboardEnter'] as const) {
+    assert.deepEqual(binding.facts.operations[operation], {
+      available: false,
+      reason: 'unsupported-provider-mode',
+    });
+  }
   // `apps` is left unclassified above (an optional cell): it inherits the network gap's reason.
   assert.deepEqual(binding.facts.operations.listApps, {
     available: false,

packages/contracts/src/platform-runtime-unavailable.ts

@@ -37,6 +37,9 @@ import { touchRuntimeOperationFacts } from './touch-runtime.ts';
 /**
  * A runtime-contract helper for provider ownership gaps. It never assigns lifecycle semantics:
  * the selected package/provider must classify every lifecycle operation for its exact cell.
+ *
+ * A family is one cell where all of its operations share one reason, and one cell per operation
+ * only where the reasons genuinely differ per operation.
  */
 export type UnavailablePlatformRuntimeFacts = Readonly<{
   appLog: RuntimeOperationUnavailability;
@@ -58,9 +61,7 @@ export type UnavailablePlatformRuntimeFacts = Readonly<{
   home: RuntimeOperationUnavailability;
   orientation: RuntimeOperationUnavailability;
   tvRemote: RuntimeOperationUnavailability;
-  keyboardStatus: RuntimeOperationUnavailability;
-  keyboardDismiss: RuntimeOperationUnavailability;
-  keyboardEnter: RuntimeOperationUnavailability;
+  keyboard: RuntimeOperationUnavailability;
   readClipboard: RuntimeOperationUnavailability;
   writeClipboard: RuntimeOperationUnavailability;
   appSwitcher: RuntimeOperationUnavailability;
@@ -116,9 +117,7 @@ const UNAVAILABLE_CELLS = {
   home: true,
   orientation: true,
   tvRemote: true,
-  keyboardStatus: true,
-  keyboardDismiss: true,
-  keyboardEnter: true,
+  keyboard: true,
   readClipboard: true,
   writeClipboard: true,
   appSwitcher: true,
@@ -245,11 +244,7 @@ export function createUnavailablePlatformRuntimeFacts(
       ...homeRuntimeOperationFacts({ home: frozen.home }),
       ...orientationRuntimeOperationFacts({ orientation: frozen.orientation }),
       ...tvRemoteRuntimeOperationFacts({ tvRemote: frozen.tvRemote }),
-      ...keyboardRuntimeOperationFacts({
-        status: frozen.keyboardStatus,
-        dismiss: frozen.keyboardDismiss,
-        enter: frozen.keyboardEnter,
-      }),
+      ...keyboardRuntimeOperationFacts({ unsupported: frozen.keyboard }),
       ...clipboardRuntimeOperationFacts({
         read: frozen.readClipboard,
         write: frozen.writeClipboard,

packages/platform-android/src/runtime.ts

@@ -76,6 +76,12 @@ const focusKindUnavailable = Object.freeze({
   reason: 'unsupported-device-kind',
   hint: 'focus is supported on Android emulators and physical devices.',
 } as const);
+/** adb drives keyboard actions on the same two kinds it drives everything else. */
+const keyboardKindUnavailable = Object.freeze({
+  available: false,
+  reason: 'unsupported-device-kind',
+  hint: 'keyboard actions are supported on Android emulators and physical devices.',
+} as const);
 const hoverUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-platform-leaf',
@@ -363,6 +369,7 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
         // The only owner with a live IME status read; dismiss/enter share every other
         // interaction cell's kind gate (parity with the retired `keyboard` bucket).
         ...keyboardRuntimeOperationFacts({
+          unsupported: keyboardKindUnavailable,
           status: androidTouchFact(device),
           dismiss: androidTouchFact(device),
           enter: androidTouchFact(device),

packages/platform-apple/src/navigation/runtime.ts

@@ -101,8 +101,11 @@ function appleTvRemoteFact(device: DeviceInfo): RuntimeOperationFact {
     : tvRemoteUnavailable;
 }
 
-/** The outer keyboard cell: unavailable with no hint, matching the retired `supportsKeyboard`
- * capability-bucket-level rejection (which carried no hint text of its own). */
+/**
+ * The outer keyboard cell, and this owner's keyboard-family refusal: unavailable with no hint,
+ * matching the retired `supportsKeyboard` capability-bucket-level rejection (which carried no hint
+ * text of its own).
+ */
 const keyboardCellUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-platform-leaf',
@@ -138,6 +141,7 @@ export function appleNavigationFacts(device: DeviceInfo) {
     ...orientationRuntimeOperationFacts({ orientation: appleOrientationFact(device) }),
     ...tvRemoteRuntimeOperationFacts({ tvRemote: appleTvRemoteFact(device) }),
     ...keyboardRuntimeOperationFacts({
+      unsupported: keyboardCellUnavailable,
       status: appleKeyboardStatusFact(device),
       dismiss: appleKeyboardDismissFact(device),
       enter: appleKeyboardEnterFact(device),

packages/platform-harmonyos/src/runtime.ts

@@ -287,7 +287,9 @@ export function createHarmonyPlatformRuntime(host: PlatformRuntimeHost): Platfor
         }),
         ...orientationRuntimeOperationFacts({ orientation: harmonyPlatformLeafUnavailable }),
         ...tvRemoteRuntimeOperationFacts({ tvRemote: harmonyPlatformLeafUnavailable }),
+        // HDC drives dismissal and the enter key; any other keyboard operation is a leaf gap.
         ...keyboardRuntimeOperationFacts({
+          unsupported: harmonyPlatformLeafUnavailable,
           status: harmonyKeyboardStatusUnavailable,
           dismiss: harmonyFocusFact(device),
           enter: harmonyFocusFact(device),

packages/platform-linux/src/runtime.ts

@@ -210,9 +210,7 @@ function linuxFacts(device: DeviceInfo): RuntimeFacts<PlatformRuntimeOperations>
     awaitAlert: linuxPlatformLeafUnavailable,
     acceptAlert: linuxPlatformLeafUnavailable,
     dismissAlert: linuxPlatformLeafUnavailable,
-    keyboardStatus: linuxPlatformLeafUnavailable,
-    keyboardDismiss: linuxPlatformLeafUnavailable,
-    keyboardEnter: linuxPlatformLeafUnavailable,
+    keyboard: linuxPlatformLeafUnavailable,
     audioProbeCapture: linuxAudioProbeUnavailable,
     audioProbeQuery: linuxAudioProbeUnavailable,
     perf: linuxPlatformLeafUnavailable,

packages/platform-vega/src/runtime.ts

@@ -200,9 +200,7 @@ function vegaFacts(device: DeviceInfo): RuntimeFacts<PlatformRuntimeOperations>
     awaitAlert: alertUnavailable,
     acceptAlert: alertUnavailable,
     dismissAlert: alertUnavailable,
-    keyboardStatus: keyboardUnavailable,
-    keyboardDismiss: keyboardUnavailable,
-    keyboardEnter: keyboardUnavailable,
+    keyboard: keyboardUnavailable,
     audioProbeCapture: audioProbeUnavailable,
     audioProbeQuery: audioProbeUnavailable,
     perf: unsupportedPlatformLeaf,

packages/platform-web/src/runtime.ts

@@ -413,11 +413,7 @@ function webRuntimeFacts(
       ...homeRuntimeOperationFacts({ home: navigationUnavailable }),
       ...orientationRuntimeOperationFacts({ orientation: navigationUnavailable }),
       ...tvRemoteRuntimeOperationFacts({ tvRemote: navigationUnavailable }),
-      ...keyboardRuntimeOperationFacts({
-        status: navigationUnavailable,
-        dismiss: navigationUnavailable,
-        enter: navigationUnavailable,
-      }),
+      ...keyboardRuntimeOperationFacts({ unsupported: navigationUnavailable }),
       // The web backend never carried a `clipboard` capability bucket (`WEB_QUERY_COMMANDS`
       // lists `audio` alone), so no clipboard cell was ever admitted here.
       ...clipboardRuntimeOperationFacts({