Skip to content

Commit 029223a

Browse files
committed
refactor(daemon): pass the platform-services fixture through the port in tests (review)
- request-recording-health, request-router-recording-health, session-device-resolution, and ios-app-session-hint now override appleSessionObservation via daemonPlatformServicesFixture instead of vi.mock-ing platform-runtime-apple-resources.ts (ADR 0019 s11) - ADR 0019 s11 and the port JSDoc reworded: the open-target and readiness members are inline signatures over neutral types, not published contract types - platformServices JSDoc moved onto its field in request-execution-scope.ts - platform-runtime-daemon-services.ts cites ADR 0019 section 11
1 parent 13d9500 commit 029223a

8 files changed

Lines changed: 89 additions & 52 deletions

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -836,9 +836,11 @@ classification. Those asks now cross the daemon boundary as one required depende
836836
`src/platform-runtime-daemon-services.ts` and threaded root → `RequestRouterDeps` → the request
837837
execution scope → the handlers and consumers.
838838

839-
The port is not a raw escape hatch back into platform mechanics. Every member is an
840-
already-published neutral contract type from `@agent-device/contracts` (or the readiness boolean),
841-
so it carries observations and classifications, never selectors, gestures, or runner calls; device
839+
The port is not a raw escape hatch back into platform mechanics. Its two observation members are
840+
already-published neutral contract types from `@agent-device/contracts`; readiness and the three
841+
open-target members are function signatures declared inline on the port, each taking and returning
842+
only neutral types such as `DeviceInfo`, the readiness boolean, and `SessionSurface`. Either way it
843+
carries observations and classifications, never selectors, gestures, or runner calls; device
842844
execution stays on the request-bound `RequestExecutionScope.bindDevice` path, whose owner facts
843845
remain the only admission authority. Its members are also all required: there is no throwing
844846
placeholder an un-composed process silently runs on — a daemon process either receives the root's

‎src/daemon/__tests__/request-recording-health.test.ts‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,22 @@ import {
99
import { LeaseRegistry } from '../lease-registry.ts';
1010
import { makeTestScreenRecordingResource } from '../../__tests__/test-utils/screen-recording-live-handle.ts';
1111

12-
vi.mock('../../platform-runtime-apple-resources.ts', async (importOriginal) => ({
13-
...(await importOriginal<typeof import('../../platform-runtime-apple-resources.ts')>()),
14-
appleSessionObservation: { observeRunnerSession: vi.fn() },
15-
}));
16-
17-
import { appleSessionObservation } from '../../platform-runtime-apple-resources.ts';
1812
import { refreshRecordingHealth } from '../request-recording-health.ts';
1913

20-
const mockObserveRunnerSession = vi.mocked(appleSessionObservation.observeRunnerSession);
14+
const mockObserveRunnerSession = vi.fn();
15+
16+
// ADR 0019 section 11: the observation stub crosses the port as a fixture override, never as a
17+
// mock of the platform module behind it.
18+
function recordingHealthPlatformServices() {
19+
const services = daemonPlatformServicesFixture();
20+
return {
21+
...services,
22+
appleSessionObservation: {
23+
...services.appleSessionObservation,
24+
observeRunnerSession: mockObserveRunnerSession,
25+
},
26+
};
27+
}
2128

2229
beforeEach(() => {
2330
mockObserveRunnerSession.mockReset();
@@ -63,7 +70,7 @@ test('runner-backed iOS recordings still invalidate on runner restarts', async (
6370

6471
const store = makeSessionStore();
6572
const ref = store.publish(session.name, session);
66-
await refreshRecordingHealth(store, ref, daemonPlatformServicesFixture());
73+
await refreshRecordingHealth(store, ref, recordingHealthPlatformServices());
6774

6875
expect(mockObserveRunnerSession).toHaveBeenCalledWith('sim-1');
6976
expect(session.screenRecording?.handle.inspect().invalidatedReason).toBe(
@@ -89,7 +96,7 @@ test.each([
8996

9097
const store = makeSessionStore();
9198
const ref = store.publish(session.name, session);
92-
await refreshRecordingHealth(store, ref, daemonPlatformServicesFixture());
99+
await refreshRecordingHealth(store, ref, recordingHealthPlatformServices());
93100

94101
expect(session.screenRecording.handle.inspect().invalidatedReason).toBe(reason);
95102
});
@@ -104,7 +111,7 @@ test('a recording without a runner identity adopts the first live observation',
104111

105112
const store = makeSessionStore();
106113
const ref = store.publish(session.name, session);
107-
await refreshRecordingHealth(store, ref, daemonPlatformServicesFixture());
114+
await refreshRecordingHealth(store, ref, recordingHealthPlatformServices());
108115

109116
const recording = session.screenRecording.handle.inspect();
110117
expect(recording.runnerSessionId).toBe('runner-first');
@@ -130,7 +137,7 @@ test.each(['rebuild', 'retire', 'handle', 'token', 'generation'] as const)(
130137
finish = resolve;
131138
}),
132139
);
133-
const observation = refreshRecordingHealth(store, ref, daemonPlatformServicesFixture());
140+
const observation = refreshRecordingHealth(store, ref, recordingHealthPlatformServices());
134141
expect(mockObserveRunnerSession).toHaveBeenCalledWith('sim-1');
135142
if (change === 'rebuild') {
136143
store.update(ref, { appName: 'Intervening app' });
@@ -198,8 +205,8 @@ test.each(['rebuild', 'retire'] as const)(
198205
sessionStore: store,
199206
leaseRegistry: new LeaseRegistry(),
200207
// Locked preparation refreshes recording health through the port, so the scope has to carry
201-
// the composed services the mocked observation spy is hanging off.
202-
platformServices: daemonPlatformServicesFixture(),
208+
// the fixture whose observation member is the spy.
209+
platformServices: recordingHealthPlatformServices(),
203210
});
204211
const prepared = scope.runLocked(() =>
205212
prepareLockedRequestScope({

‎src/daemon/__tests__/request-router-recording-health.test.ts‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,7 @@ import { test, expect, vi, beforeEach } from 'vitest';
44

55
import path from 'node:path';
66

7-
vi.mock('../../platform-runtime-apple-resources.ts', async (importOriginal) => ({
8-
...(await importOriginal<typeof import('../../platform-runtime-apple-resources.ts')>()),
9-
appleSessionObservation: { observeRunnerSession: vi.fn() },
10-
}));
11-
12-
import { appleSessionObservation } from '../../platform-runtime-apple-resources.ts';
7+
import { daemonPlatformServicesFixture } from './platform-services-fixture.ts';
138
import {
149
createRequestHandler,
1510
gestureDeviceRuntimeGateway,
@@ -21,7 +16,7 @@ import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
2116
import { makeTestScreenRecordingResource } from '../../__tests__/test-utils/screen-recording-live-handle.ts';
2217
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
2318

24-
const mockObserveRunnerSession = vi.mocked(appleSessionObservation.observeRunnerSession);
19+
const mockObserveRunnerSession = vi.fn();
2520

2621
beforeEach(() => {
2722
legacyDispatchCapture.mockReset();
@@ -30,6 +25,19 @@ beforeEach(() => {
3025
mockObserveRunnerSession.mockReset();
3126
});
3227

28+
// ADR 0019 section 11: the observation stub crosses the port as a fixture override, never as a
29+
// mock of the platform module behind it.
30+
function recordingHealthPlatformServices() {
31+
const services = daemonPlatformServicesFixture();
32+
return {
33+
...services,
34+
appleSessionObservation: {
35+
...services.appleSessionObservation,
36+
observeRunnerSession: mockObserveRunnerSession,
37+
},
38+
};
39+
}
40+
3341
test('router blocks non-record commands when recording was invalidated', async () => {
3442
const sessionStore = makeSessionStore('agent-device-router-recording-health-');
3543
const session: SessionState = {
@@ -62,6 +70,7 @@ test('router blocks non-record commands when recording was invalidated', async (
6270
leaseRegistry: new LeaseRegistry(),
6371
deviceInventoryGateways: createTestDeviceInventoryGateways(),
6472
trackDownloadableArtifact: () => 'artifact-id',
73+
platformServices: recordingHealthPlatformServices(),
6574
});
6675

6776
const response = await handler({
@@ -117,6 +126,7 @@ test('router allows canonical iOS simulator gestures during overlay recording af
117126
deviceInventoryGateways: createTestDeviceInventoryGateways(),
118127
trackDownloadableArtifact: () => 'artifact-id',
119128
deviceRuntimeGateway: gestureDeviceRuntimeGateway,
129+
platformServices: recordingHealthPlatformServices(),
120130
});
121131

122132
const response = await handler({

‎src/daemon/__tests__/session-device-resolution.test.ts‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,11 @@ import {
88
refreshSessionDeviceIfNeeded,
99
selectorTargetsSessionDevice,
1010
} from '../session-device-resolution.ts';
11-
import { appleSessionObservation } from '../../platform-runtime-apple-resources.ts';
1211
import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
1312
import { isActiveProviderDevice } from '../provider-device-admission.ts';
1413
import { ensureDeviceReady } from '../device/device-ready.ts';
1514
import { PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
1615

17-
vi.mock('../../platform-runtime-apple-resources.ts', async (importOriginal) => ({
18-
...(await importOriginal<typeof import('../../platform-runtime-apple-resources.ts')>()),
19-
appleSessionObservation: { observeRunnerSession: vi.fn() },
20-
}));
2116
vi.mock('@agent-device/device-selection/dispatch-resolve', () => ({
2217
resolveTargetDevice: vi.fn(),
2318
}));
@@ -28,10 +23,23 @@ vi.mock('../device/device-ready.ts', () => ({
2823
ensureDeviceReady: vi.fn(async () => {}),
2924
}));
3025

31-
const mockObserveRunnerSession = vi.mocked(appleSessionObservation.observeRunnerSession);
3226
const mockResolveTargetDevice = vi.mocked(resolveTargetDevice);
3327
const mockIsActiveProviderDevice = vi.mocked(isActiveProviderDevice);
3428
const mockEnsureDeviceReady = vi.mocked(ensureDeviceReady);
29+
const mockObserveRunnerSession = vi.fn();
30+
31+
// ADR 0019 section 11: the observation stub crosses the port as a fixture override, never as a
32+
// mock of the platform module behind it.
33+
function platformServicesWithObservation() {
34+
const services = daemonPlatformServicesFixture();
35+
return {
36+
...services,
37+
appleSessionObservation: {
38+
...services.appleSessionObservation,
39+
observeRunnerSession: mockObserveRunnerSession,
40+
},
41+
};
42+
}
3543

3644
beforeEach(() => {
3745
mockObserveRunnerSession.mockReset();
@@ -68,7 +76,7 @@ async function withMockedPlatform<T>(platform: NodeJS.Platform, fn: () => Promis
6876

6977
test('refreshSessionDeviceIfNeeded keeps iOS simulator session device on non-mac hosts', async () => {
7078
const device = await withMockedPlatform('linux', async () =>
71-
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, daemonPlatformServicesFixture()),
79+
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, platformServicesWithObservation()),
7280
);
7381

7482
expect(device).toBe(iosSimulatorSession.device);
@@ -79,7 +87,7 @@ test('resolveCommandDevice keeps an existing session for a platform-only filter'
7987
'linux',
8088
async () =>
8189
await resolveCommandDevice({
82-
platformServices: daemonPlatformServicesFixture(),
90+
platformServices: platformServicesWithObservation(),
8391
session: iosSimulatorSession,
8492
flags: { platform: 'ios' },
8593
}),
@@ -96,7 +104,7 @@ test('resolveCommandDevice does not prepare a sessionless device', async () => {
96104
await resolveCommandDevice({
97105
session: undefined,
98106
flags: { platform: 'ios' },
99-
platformServices: daemonPlatformServicesFixture(),
107+
platformServices: platformServicesWithObservation(),
100108
});
101109

102110
expect(mockResolveTargetDevice).toHaveBeenCalledOnce();
@@ -109,7 +117,7 @@ test('refreshSessionDeviceIfNeeded keeps provider-owned iOS simulators out of lo
109117
const device = await withMockedPlatform('darwin', async () =>
110118
refreshSessionDeviceIfNeeded(
111119
{ ...iosSimulatorSession.device, id: 'limrun:ios:lease-1' },
112-
daemonPlatformServicesFixture(),
120+
platformServicesWithObservation(),
113121
),
114122
);
115123

@@ -124,7 +132,7 @@ test('refreshSessionDeviceIfNeeded skips re-resolve while the iOS runner session
124132
});
125133

126134
const device = await withMockedPlatform('darwin', async () =>
127-
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, daemonPlatformServicesFixture()),
135+
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, platformServicesWithObservation()),
128136
);
129137

130138
expect(device).toEqual({ ...iosSimulatorSession.device, booted: true });
@@ -140,7 +148,7 @@ test('refreshSessionDeviceIfNeeded re-resolves when the iOS runner session is go
140148
mockResolveTargetDevice.mockResolvedValue(resolved);
141149

142150
const device = await withMockedPlatform('darwin', async () =>
143-
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, daemonPlatformServicesFixture()),
151+
refreshSessionDeviceIfNeeded(iosSimulatorSession.device, platformServicesWithObservation()),
144152
);
145153

146154
expect(device).toBe(resolved);

‎src/daemon/ios-app-session-hint.test.ts‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,18 @@ import { beforeEach, expect, test, vi } from 'vitest';
33
import { IOS_DEVICE, IOS_SIMULATOR } from '../__tests__/test-utils/device-fixtures.ts';
44
import { buildIosOpenCommandHint } from './ios-app-session-hint.ts';
55

6-
const resolveSoleForegroundApp = vi.hoisted(() => vi.fn());
7-
vi.mock('../platform-runtime-apple-resources.ts', () => ({
8-
appleSessionObservation: { resolveSoleForegroundApp },
9-
}));
6+
const resolveSoleForegroundApp = vi.fn();
7+
8+
// ADR 0019 section 11: the observation stub crosses the port as a fixture override, never as a
9+
// mock of the platform module behind it.
10+
function hintPlatformServices() {
11+
return daemonPlatformServicesFixture({
12+
appleSessionObservation: {
13+
observeRunnerSession: vi.fn(async () => undefined),
14+
resolveSoleForegroundApp,
15+
},
16+
});
17+
}
1018

1119
beforeEach(() => {
1220
resolveSoleForegroundApp.mockReset();
@@ -19,7 +27,7 @@ test('an unambiguous environment gets the exact runnable open command', async ()
1927
app: { bundleId: 'xyz.blueskyweb.app' },
2028
});
2129

22-
const hint = await buildIosOpenCommandHint(IOS_SIMULATOR, daemonPlatformServicesFixture());
30+
const hint = await buildIosOpenCommandHint(IOS_SIMULATOR, hintPlatformServices());
2331

2432
expect(hint).toBe(
2533
'One booted device found ("iPhone 16", udid booted-1) with xyz.blueskyweb.app running. ' +
@@ -40,7 +48,7 @@ test('a custom simulator set is echoed back so the printed command is the one th
4048
app: { bundleId: 'xyz.blueskyweb.app' },
4149
});
4250

43-
const hint = await buildIosOpenCommandHint(soleBootedDevice, daemonPlatformServicesFixture());
51+
const hint = await buildIosOpenCommandHint(soleBootedDevice, hintPlatformServices());
4452

4553
expect(hint).toBe(
4654
'One booted device found ("iPhone 16", udid booted-1) with xyz.blueskyweb.app running. ' +
@@ -66,28 +74,28 @@ test('a hint that would exceed the wire-redaction truncation length falls back t
6674
});
6775

6876
await expect(
69-
buildIosOpenCommandHint(soleBootedDevice, daemonPlatformServicesFixture()),
77+
buildIosOpenCommandHint(soleBootedDevice, hintPlatformServices()),
7078
).resolves.toBeUndefined();
7179
});
7280

7381
test('an inconclusive observation keeps the generic hint', async () => {
7482
resolveSoleForegroundApp.mockResolvedValue(undefined);
7583
await expect(
76-
buildIosOpenCommandHint(IOS_SIMULATOR, daemonPlatformServicesFixture()),
84+
buildIosOpenCommandHint(IOS_SIMULATOR, hintPlatformServices()),
7785
).resolves.toBeUndefined();
7886
});
7987

8088
test('control-flow failures from the observation port propagate', async () => {
8189
const canceled = new DOMException('This operation was aborted', 'AbortError');
8290
resolveSoleForegroundApp.mockRejectedValue(canceled);
83-
await expect(
84-
buildIosOpenCommandHint(IOS_SIMULATOR, daemonPlatformServicesFixture()),
85-
).rejects.toBe(canceled);
91+
await expect(buildIosOpenCommandHint(IOS_SIMULATOR, hintPlatformServices())).rejects.toBe(
92+
canceled,
93+
);
8694
});
8795

8896
test('a physical iOS device never probes for a hint', async () => {
8997
await expect(
90-
buildIosOpenCommandHint(IOS_DEVICE, daemonPlatformServicesFixture()),
98+
buildIosOpenCommandHint(IOS_DEVICE, hintPlatformServices()),
9199
).resolves.toBeUndefined();
92100
expect(resolveSoleForegroundApp).not.toHaveBeenCalled();
93101
});

‎src/daemon/platform-services.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,11 @@ export type EnsureLocalDeviceReady = (device: DeviceInfo) => Promise<boolean>;
1111

1212
/**
1313
* Root-composed platform services the daemon asks of the host machine for work that binds no
14-
* device runtime. Every member is an already-published neutral contract over mechanics the daemon
15-
* must never name or load itself: concrete local readiness, boot-time and runner-session
16-
* observation, and open-target classification. Device execution is NOT in this port and never
14+
* device runtime. Every member is a neutral contract over mechanics the daemon must never name or
15+
* load itself: concrete local readiness, boot-time and runner-session observation, and open-target
16+
* classification. The observation members are published contract types; the rest are signatures
17+
* declared inline here, taking and returning only neutral types.
18+
* Device execution is NOT in this port and never
1719
* enters it (ADR 0019): it goes through the request-bound runtime binding
1820
* (`RequestExecutionScope.bindDevice`), whose owner facts stay the only admission authority.
1921
*/

‎src/daemon/request-execution-scope.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,10 +101,10 @@ export type RequestExecutionScope = AsyncDisposable & {
101101
runLocked<T>(task: () => Promise<T>): Promise<T>;
102102
retainDeviceExecutionLock(deviceId: string): Promise<void>;
103103
bindDevice: BindDeviceRuntime;
104+
/** Root-composed platform services for this request's asks that bind no device runtime. */
104105
platformServices: DaemonPlatformServices;
105106
inspectFacts: InspectDeviceRuntimeFacts;
106107
bindExactDevice: BindExactDeviceRuntime;
107-
/** Root-composed platform services for this request's asks that bind no device runtime. */
108108
/** The request's mutations, recorded by every bound operation this scope hands out. */
109109
dispatchLedger: RequestDispatchLedger;
110110
throwIfCanceled(): void;

‎src/platform-runtime-daemon-services.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import {
99
import type { DaemonPlatformServices } from './daemon/platform-services.ts';
1010

1111
/**
12-
* Root composition of the daemon's platform-services port (ADR 0019 section 1). Each member is
12+
* Root composition of the daemon's platform-services port (ADR 0019 section 11). Each member is
1313
* already the neutral contract the daemon consumes; this module is what names the concrete
1414
* adapters, so no daemon file has to. Device execution never enters here — it reaches the device
1515
* through the request-bound runtime binding, whose owner facts stay the only admission authority.

0 commit comments

Comments
 (0)