refactor(contracts): build unavailable runtime facts once (#2291)

* refactor(contracts): build unavailable runtime facts from one policy table

freezeUnavailableFacts() classified each of the 34 UnavailablePlatformRuntimeFacts
cells with its own Object.freeze call and its own inline comment, and
createUnavailablePlatformRuntimeFacts() destructured all 38 fields off the
result before spreading them into the operations map. Replace the per-field
freezes with a single UNAVAILABLE_CELL_POLICY table (satisfies
Record<UnavailableCellKey, 'owner-stated' | 'inherits-network'>) and a loop, so
a new cell added to UnavailablePlatformRuntimeFacts must get a policy entry or
the file fails to type-check. The scattered per-field comments collapse into
one block comment above the table citing #1873. Drop the 39-line destructure;
createUnavailablePlatformRuntimeFacts now reads the frozen record's fields
directly.

Add createFullyUnavailablePlatformRuntimeFacts(), an exported constructor that
points every cell (lifecycle included) at one unavailability reason, for
missing-owner cases that have no per-family classification of their own.

Verified the table forces every cell to be classified: flipping `apps` from
'inherits-network' to 'owner-stated' (an optional cell most local runtimes
still leave unclassified) is not a type error, since the table only governs
runtime fallback and the field stays optional either way — but it does turn
into a real test failure: packages/platform-linux/src/runtime.test.ts's
`listApps` assertion goes from `{ available: false }` to `{}`, because the
loop now treats an unclassified `apps` cell as owner-stated and stops falling
back to the network gap. Reverted before committing.

* refactor(gateway): reuse the shared fully-unavailable facts constructor

unavailableProviderBinding() and unavailableProviderFacts() each hand-spelled
every UnavailablePlatformRuntimeFacts cell for a provider mode with no
registered module. The two lists had already drifted: the binding map omitted
`readiness`, the facts map included it — harmless only because both fall back
to the same 'unsupported-provider-mode' reason today, but nothing would have
caught a real divergence. Both become one-liners over
createFullyUnavailablePlatformRuntimeFacts(), so there is exactly one place
that enumerates "every cell is this one reason", and unavailableProviderLifecycleFacts()
is no longer needed.

Added a regression test asserting bind() and inspectFacts() produce
byte-for-byte equal facts for the same unregistered-provider device: it
passes today (confirmed against the pre-refactor gateway.ts, restored
temporarily to check) since the drift was reason-compatible, but it now pins
that equivalence so a future cell added to only one of the two paths fails
loudly instead of silently drifting again.

* refactor(contracts): derive unavailable-cell fallback from optionality

UNAVAILABLE_CELL_POLICY hand-duplicated which cells inherit the
network gap and which are owner-stated, restating exactly what
UnavailablePlatformRuntimeFacts's optional vs required properties
already say. Nothing checked the two against each other, so a
misclassified entry passed `satisfies Record<UnavailableCellKey,
'owner-stated' | 'inherits-network'>` and the cast at the read site
turned it into `Object.freeze({ ...undefined })` = `{}` at runtime -
a fact object missing `available` entirely.

Replaced the two-value table with a key-only UNAVAILABLE_CELLS list
and one `mapUnavailableCells` helper shared by both call sites.
freezeUnavailableFacts now reads `unavailable[cell] ?? unavailable.network`,
which TypeScript resolves without a cast because the union already
covers the optional case - a wrong classification is impossible to
express, not just checked for.

Seen red once: reverted the `?? unavailable.network` fallback (kept
`unavailable[cell]` alone) and reran
platform-runtime-unavailable.test.ts - the new `listApps` assertion
failed with the exact `{}` malformed-fact shape the policy-table bug
could produce. Restored the fallback and it passes.

Also added the missing inherits-network assertion itself
(platform-runtime-unavailable.test.ts): the existing test only
exercised owner-stated cells, so the inheriting path had no direct
coverage in this file.

* test(gateway): fold bind/inspect parity into the existing fixture

The parity test duplicated the whole gateway construction (single
apple module, inline webdriver ProviderDeviceRuntime literal) from
the test directly above it instead of reusing it. Appended the
inspectFacts() call and the equality assertion to that test instead,
and switched toEqual to toStrictEqual: toEqual ignores
undefined-valued keys, and an omitted cell is exactly how the two
facts maps could drift from each other.

Author: thymikee

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

@@ -92,6 +92,11 @@ test('generic unavailable binding preserves exact provider ownership and mode',
     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,
+    reason: 'owner-capability-missing',
+  });
   assert.deepEqual(binding.operations, {});
   await binding[Symbol.asyncDispose]();
 });

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

@@ -87,6 +87,89 @@ type FrozenUnavailablePlatformRuntimeFacts = Readonly<
     Readonly<{ lifecycle: ApplicationLifecycleOperationFacts }>
 >;
 
+type UnavailableCellKey = keyof Omit<UnavailablePlatformRuntimeFacts, 'lifecycle'>;
+
+/**
+ * Every cell name, for iteration. Whether a cell left unclassified by its owner falls back to the
+ * caller's network gap, or must be stated by the owner itself, is decided by
+ * `UnavailablePlatformRuntimeFacts` alone: an optional property inherits `network`, a required one
+ * is owner-stated (#1873) and always present. No second table restates that split — a misclassified
+ * cell there would fail to type-check rather than silently produce a malformed fact.
+ */
+const UNAVAILABLE_CELLS = {
+  appLog: true,
+  apps: true,
+  appDeployment: true,
+  appState: true,
+  network: true,
+  screenRecording: true,
+  screenshot: true,
+  snapshot: true,
+  viewport: true,
+  focus: true,
+  gesture: true,
+  scroll: true,
+  typeText: true,
+  touch: true,
+  elementText: true,
+  back: true,
+  home: true,
+  orientation: true,
+  tvRemote: true,
+  keyboardStatus: true,
+  keyboardDismiss: true,
+  keyboardEnter: true,
+  readClipboard: true,
+  writeClipboard: true,
+  appSwitcher: true,
+  triggerAppEvent: true,
+  setSetting: true,
+  readAlert: true,
+  awaitAlert: true,
+  acceptAlert: true,
+  dismissAlert: true,
+  audioProbeCapture: true,
+  audioProbeQuery: true,
+  perf: true,
+  readiness: true,
+  shutdown: true,
+} satisfies Record<UnavailableCellKey, true>;
+
+/** Fills every cell name through `fn`, in the one place a cell record is assembled by key. */
+function mapUnavailableCells<Value>(
+  fn: (cell: UnavailableCellKey) => Value,
+): Record<UnavailableCellKey, Value> {
+  const result = {} as Record<UnavailableCellKey, Value>;
+  for (const cell of Object.keys(UNAVAILABLE_CELLS) as UnavailableCellKey[]) {
+    result[cell] = fn(cell);
+  }
+  return result;
+}
+
+/**
+ * A complete facts value for one unavailability reason, for owners with no runtime module at all:
+ * every cell, lifecycle included, reports the same reason, so a missing owner cannot leave a cell
+ * unclassified by omission.
+ */
+export function createFullyUnavailablePlatformRuntimeFacts(
+  unavailable: RuntimeOperationUnavailability,
+): UnavailablePlatformRuntimeFacts {
+  return Object.freeze({
+    ...mapUnavailableCells(() => unavailable),
+    lifecycle: applicationLifecycleOperationFacts({
+      resolveOpenTarget: unavailable,
+      prepareApplicationOpen: unavailable,
+      openApplication: unavailable,
+      applyRuntimeHints: unavailable,
+      clearRuntimeHints: unavailable,
+      closeApplication: unavailable,
+      finalizeApplicationClose: unavailable,
+      prepareAppleRunner: unavailable,
+      configureProviderPortReverse: unavailable,
+    }),
+  });
+}
+
 export function createUnavailablePlatformRuntimeBinding(
   device: DeviceInfo,
   owner: RuntimeOwnerRef,
@@ -106,136 +189,101 @@ export function createUnavailablePlatformRuntimeFacts(
   owner: RuntimeOwnerRef,
   unavailable: UnavailablePlatformRuntimeFacts,
 ): RuntimeFacts<PlatformRuntimeOperations> {
-  const {
-    appLog,
-    apps,
-    appDeployment,
-    appState,
-    network,
-    screenRecording,
-    screenshot,
-    snapshot,
-    viewport,
-    focus,
-    gesture,
-    scroll,
-    typeText,
-    touch,
-    elementText,
-    back,
-    home,
-    orientation,
-    tvRemote,
-    keyboardStatus,
-    keyboardDismiss,
-    keyboardEnter,
-    readClipboard,
-    writeClipboard,
-    appSwitcher,
-    triggerAppEvent,
-    setSetting,
-    readAlert,
-    awaitAlert,
-    acceptAlert,
-    dismissAlert,
-    audioProbeCapture,
-    audioProbeQuery,
-    perf,
-    readiness,
-    shutdown,
-    lifecycle,
-  } = freezeUnavailableFacts(unavailable);
+  const frozen = freezeUnavailableFacts(unavailable);
   return Object.freeze({
     device: {
       ...deviceShape(device),
       providerMode: providerModeForOwner(owner),
     },
     operations: {
-      appLogInspect: appLog,
-      appLogDoctor: appLog,
-      appLogStart: appLog,
-      appLogReattach: appLog,
-      appLogCleanup: appLog,
-      listApps: apps,
-      deployApp: appDeployment,
-      materializeAppSource: appDeployment,
-      deployMaterializedApp: appDeployment,
-      sendPushNotification: appDeployment,
-      appState,
-      networkDump: network,
-      screenRecordingStart: screenRecording,
-      screenRecordingReattach: screenRecording,
-      screenRecordingCleanup: screenRecording,
-      ...screenshotRuntimeOperationFacts({ capture: screenshot }),
+      appLogInspect: frozen.appLog,
+      appLogDoctor: frozen.appLog,
+      appLogStart: frozen.appLog,
+      appLogReattach: frozen.appLog,
+      appLogCleanup: frozen.appLog,
+      listApps: frozen.apps,
+      deployApp: frozen.appDeployment,
+      materializeAppSource: frozen.appDeployment,
+      deployMaterializedApp: frozen.appDeployment,
+      sendPushNotification: frozen.appDeployment,
+      appState: frozen.appState,
+      networkDump: frozen.network,
+      screenRecordingStart: frozen.screenRecording,
+      screenRecordingReattach: frozen.screenRecording,
+      screenRecordingCleanup: frozen.screenRecording,
+      ...screenshotRuntimeOperationFacts({ capture: frozen.screenshot }),
       ...snapshotRuntimeOperationFacts({
-        capture: snapshot,
-        customActions: snapshot,
-        withoutActiveApp: snapshot,
+        capture: frozen.snapshot,
+        customActions: frozen.snapshot,
+        withoutActiveApp: frozen.snapshot,
       }),
       // The preferred text reading starts unavailable for every family, on the same sentinel as
       // capture: an owner that has a native reading declares it explicitly, and one that does not
       // sends every text wait to the canonical tree.
       ...selectorObservationRuntimeOperationFacts({
-        findText: snapshot,
-        findSelector: snapshot,
+        findText: frozen.snapshot,
+        findSelector: frozen.snapshot,
       }),
-      ...viewportRuntimeOperationFacts({ setViewport: viewport }),
-      ...focusRuntimeOperationFacts({ focus }),
+      ...viewportRuntimeOperationFacts({ setViewport: frozen.viewport }),
+      ...focusRuntimeOperationFacts({ focus: frozen.focus }),
       ...gestureRuntimeOperationFacts({
-        plan: gesture,
-        directionalFling: gesture,
-        multiTouch: gesture,
-        targetAuthoredDrag: gesture,
-        viewport: gesture,
+        plan: frozen.gesture,
+        directionalFling: frozen.gesture,
+        multiTouch: frozen.gesture,
+        targetAuthoredDrag: frozen.gesture,
+        viewport: frozen.gesture,
       }),
-      ...scrollRuntimeOperationFacts({ scroll }),
-      ...typeTextRuntimeOperationFacts({ type: typeText }),
+      ...scrollRuntimeOperationFacts({ scroll: frozen.scroll }),
+      ...typeTextRuntimeOperationFacts({ type: frozen.typeText }),
       ...touchRuntimeOperationFacts({
-        tap: touch,
-        tapRef: touch,
-        longPress: touch,
-        hover: touch,
-        hoverRef: touch,
-        fill: touch,
-        fillRef: touch,
-        tapElementSelector: touch,
+        tap: frozen.touch,
+        tapRef: frozen.touch,
+        longPress: frozen.touch,
+        hover: frozen.touch,
+        hoverRef: frozen.touch,
+        fill: frozen.touch,
+        fillRef: frozen.touch,
+        tapElementSelector: frozen.touch,
       }),
-      ...elementTextRuntimeOperationFacts({ readTextAtPoint: elementText }),
-      ...backRuntimeOperationFacts({ back }),
-      ...homeRuntimeOperationFacts({ home }),
-      ...orientationRuntimeOperationFacts({ orientation }),
-      ...tvRemoteRuntimeOperationFacts({ tvRemote }),
+      ...elementTextRuntimeOperationFacts({ readTextAtPoint: frozen.elementText }),
+      ...backRuntimeOperationFacts({ back: frozen.back }),
+      ...homeRuntimeOperationFacts({ home: frozen.home }),
+      ...orientationRuntimeOperationFacts({ orientation: frozen.orientation }),
+      ...tvRemoteRuntimeOperationFacts({ tvRemote: frozen.tvRemote }),
       ...keyboardRuntimeOperationFacts({
-        status: keyboardStatus,
-        dismiss: keyboardDismiss,
-        enter: keyboardEnter,
+        status: frozen.keyboardStatus,
+        dismiss: frozen.keyboardDismiss,
+        enter: frozen.keyboardEnter,
+      }),
+      ...clipboardRuntimeOperationFacts({
+        read: frozen.readClipboard,
+        write: frozen.writeClipboard,
       }),
-      ...clipboardRuntimeOperationFacts({ read: readClipboard, write: writeClipboard }),
-      ...appSwitcherRuntimeOperationFacts({ appSwitcher }),
-      ...appEventRuntimeOperationFacts({ triggerAppEvent }),
-      ...settingsRuntimeOperationFacts({ setSetting }),
+      ...appSwitcherRuntimeOperationFacts({ appSwitcher: frozen.appSwitcher }),
+      ...appEventRuntimeOperationFacts({ triggerAppEvent: frozen.triggerAppEvent }),
+      ...settingsRuntimeOperationFacts({ setSetting: frozen.setSetting }),
       ...alertRuntimeOperationFacts({
-        read: readAlert,
-        wait: awaitAlert,
-        accept: acceptAlert,
-        dismiss: dismissAlert,
+        read: frozen.readAlert,
+        wait: frozen.awaitAlert,
+        accept: frozen.acceptAlert,
+        dismiss: frozen.dismissAlert,
       }),
       ...audioProbeRuntimeOperationFacts({
-        capture: audioProbeCapture,
-        query: audioProbeQuery,
+        capture: frozen.audioProbeCapture,
+        query: frozen.audioProbeQuery,
       }),
       ...perfRuntimeOperationFacts({
-        frames: perf,
-        memorySample: perf,
-        memorySnapshot: perf,
-        nativeCapture: perf,
-        profileReport: perf,
+        frames: frozen.perf,
+        memorySample: frozen.perf,
+        memorySnapshot: frozen.perf,
+        nativeCapture: frozen.perf,
+        profileReport: frozen.perf,
       }),
-      ensureReady: readiness,
-      bootTarget: readiness,
-      bootTargetHeadless: readiness,
-      shutdownTarget: shutdown,
-      ...lifecycle,
+      ensureReady: frozen.readiness,
+      bootTarget: frozen.readiness,
+      bootTargetHeadless: frozen.readiness,
+      shutdownTarget: frozen.shutdown,
+      ...frozen.lifecycle,
     },
   });
 }
@@ -254,66 +302,10 @@ function providerModeForOwner(owner: RuntimeOwnerRef): RuntimeProviderMode {
 function freezeUnavailableFacts(
   unavailable: UnavailablePlatformRuntimeFacts,
 ): FrozenUnavailablePlatformRuntimeFacts {
-  // Every optional cell falls back to the caller's network gap: an owner that did not classify a
-  // family has, by construction, the same reason its transport does.
-  const orNetwork = (fact: RuntimeOperationUnavailability | undefined) =>
-    Object.freeze({ ...(fact ?? unavailable.network) });
   return Object.freeze({
-    appLog: Object.freeze({ ...unavailable.appLog }),
-    apps: orNetwork(unavailable.apps),
-    appDeployment: orNetwork(unavailable.appDeployment),
-    appState: orNetwork(unavailable.appState),
-    network: Object.freeze({ ...unavailable.network }),
-    screenRecording: orNetwork(unavailable.screenRecording),
-    // Capture cells are stated by their owner, never inherited from the transport gap (#1873).
-    screenshot: Object.freeze({ ...unavailable.screenshot }),
-    snapshot: orNetwork(unavailable.snapshot),
-    viewport: Object.freeze({ ...unavailable.viewport }),
-    // Interaction cells are stated by their owner: a family that can drive touch says so for its
-    // exact kinds, and one that cannot must say why rather than inherit a transport gap.
-    focus: Object.freeze({ ...unavailable.focus }),
-    gesture: Object.freeze({ ...unavailable.gesture }),
-    scroll: Object.freeze({ ...unavailable.scroll }),
-    typeText: Object.freeze({ ...unavailable.typeText }),
-    touch: Object.freeze({ ...unavailable.touch }),
-    readiness: orNetwork(unavailable.readiness),
-    shutdown: orNetwork(unavailable.shutdown),
-    elementText: Object.freeze({ ...unavailable.elementText }),
-    // Navigation and keyboard cells are stated by their owner too: each differs by family
-    // (harmonyos drives back/home but not orientation/tvRemote; android alone answers a keyboard
-    // status read), so none of them may inherit a sibling's gap.
-    back: Object.freeze({ ...unavailable.back }),
-    home: Object.freeze({ ...unavailable.home }),
-    orientation: Object.freeze({ ...unavailable.orientation }),
-    tvRemote: Object.freeze({ ...unavailable.tvRemote }),
-    keyboardStatus: Object.freeze({ ...unavailable.keyboardStatus }),
-    keyboardDismiss: Object.freeze({ ...unavailable.keyboardDismiss }),
-    keyboardEnter: Object.freeze({ ...unavailable.keyboardEnter }),
-    // Clipboard cells are stated by their owner for the same reason: the surface differs by leaf
-    // and kind (an Apple simulator has one, a physical non-macOS Apple device does not), and read
-    // and write can diverge on a provider whose extension exposes only one half.
-    readClipboard: Object.freeze({ ...unavailable.readClipboard }),
-    writeClipboard: Object.freeze({ ...unavailable.writeClipboard }),
-    // The app switcher is the springboard surface `home` drives, and differs by owner the same
-    // way: an owner states it for its exact leaf rather than inheriting a sibling's gap.
-    appSwitcher: Object.freeze({ ...unavailable.appSwitcher }),
-    // App-event delivery opens a URL on the device, which is not something a transport gap can
-    // speak for: each owner states whether it can open one at all.
-    triggerAppEvent: Object.freeze({ ...unavailable.triggerAppEvent }),
-    // Device settings differ by leaf and kind the way the pasteboard does, and a provider can
-    // own a device without exposing any settings API at all, so each owner states its own cell.
-    setSetting: Object.freeze({ ...unavailable.setSetting }),
-    readAlert: Object.freeze({ ...unavailable.readAlert }),
-    awaitAlert: Object.freeze({ ...unavailable.awaitAlert }),
-    acceptAlert: Object.freeze({ ...unavailable.acceptAlert }),
-    dismissAlert: Object.freeze({ ...unavailable.dismissAlert }),
-    // Audio cells are stated by their owner (#1873): host capture and the page probe live on
-    // different families entirely, so neither may inherit a transport gap.
-    audioProbeCapture: Object.freeze({ ...unavailable.audioProbeCapture }),
-    audioProbeQuery: Object.freeze({ ...unavailable.audioProbeQuery }),
-    // Perf starts native tools and may create a durable capture. Every exact owner states the
-    // gap rather than inheriting a transport failure that could imply local-tool fallthrough.
-    perf: orNetwork(unavailable.perf),
+    ...mapUnavailableCells((cell) =>
+      Object.freeze({ ...(unavailable[cell] ?? unavailable.network) }),
+    ),
     lifecycle: applicationLifecycleOperationFacts(unavailable.lifecycle),
   });
 }

src/platform-runtime-gateway.test.ts

@@ -514,6 +514,10 @@ describe('composed platform runtime gateway', () => {
     });
     expect(hostLoad).not.toHaveBeenCalled();
     expect(localLoad).not.toHaveBeenCalled();
+    const inspected = await runtimeGateway.inspectFacts(device);
+    // The bind and inspect arms build this fact set independently; both must derive from the same
+    // construction path rather than two hand-maintained maps that can drift from each other.
+    expect(binding.facts).toStrictEqual(inspected);
   });
 
   test.each(LIFECYCLE_FACETS)(