Skip to content

Commit bd49bf8

Browse files
committed
refactor(contracts): share the inventory composition assertions with the test fake
Move assertProviderOutcome and assertSourceFamily from src/platform-runtime-device-inventory.ts into @agent-device/contracts/device (device-inventory.ts, exported through ./device). The test fake in device-selection previously restated the provider flow without the outcome assertion, so a malformed provider outcome surfaced as a TypeError or fell through instead of the provider_inventory_contract_violation AppError. Both the production composer and the fake now call the same validators, and a fixture test pins the fail-closed behavior on the fake. The fake's local path keeps its per-family filter: the local option is a flat whole-inventory discoverer fanned out per family, so filtering there is the adapter to the per-family source contract rather than a contract the fake would assert against itself.
1 parent c61535e commit bd49bf8

5 files changed

Lines changed: 79 additions & 24 deletions

File tree

‎packages/contracts/src/device-inventory.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,11 @@ import {
55
type DeviceInfo,
66
type DeviceKind,
77
type DeviceTarget,
8+
type Platform,
89
type PlatformSelector,
910
} from '@agent-device/kernel/device';
11+
import { AppError } from '@agent-device/kernel/errors';
12+
import type { ProviderDeviceInventorySource } from './device-provider.ts';
1013

1114
export const LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS = [
1215
'android',
@@ -69,6 +72,39 @@ export function countDeviceInventoryByGroup(devices: DeviceInfo[]): DeviceInvent
6972
return counts;
7073
}
7174

75+
/**
76+
* The composition-level contract every device-inventory source must honor: a family's
77+
* source only ever reports devices of its own family. Both the production composer and
78+
* the test fake enforce this through one implementation.
79+
*/
80+
export function assertSourceFamily(family: Platform, devices: readonly DeviceInfo[]): void {
81+
const outside = devices.find((device) => device.platform !== family);
82+
if (!outside) return;
83+
throw new AppError(
84+
'COMMAND_FAILED',
85+
`Platform inventory source ${family} returned a ${outside.platform} device.`,
86+
{ expectedFamily: family, actualFamily: outside.platform, deviceId: outside.id },
87+
);
88+
}
89+
90+
/**
91+
* Validates a raw provider discover result before the composer trusts it. A malformed
92+
* outcome (not a declined/inventory tagged object) is a provider contract violation, not
93+
* a local-inventory fallback.
94+
*/
95+
export function assertProviderOutcome(
96+
value: unknown,
97+
): asserts value is Awaited<ReturnType<ProviderDeviceInventorySource['discover']>> {
98+
if (value !== null && typeof value === 'object') {
99+
const outcome = value as { kind?: unknown; devices?: unknown };
100+
if (outcome.kind === 'declined' && !('devices' in outcome)) return;
101+
if (outcome.kind === 'inventory' && Array.isArray(outcome.devices)) return;
102+
}
103+
throw new AppError('COMMAND_FAILED', 'Provider device inventory returned an invalid outcome.', {
104+
reason: 'provider_inventory_contract_violation',
105+
});
106+
}
107+
72108
export function filterDeviceInventoryProjection(
73109
devices: readonly DeviceInfo[],
74110
request: Pick<DeviceInventoryRequest, 'platform' | 'target' | 'kind' | 'booted'>,

‎packages/contracts/src/facades/device.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ export type { AppStateCommandResult } from '../app-state.ts';
55
export {
66
LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS,
77
WEB_DESKTOP_DEVICE,
8+
assertProviderOutcome,
9+
assertSourceFamily,
810
countDeviceInventoryByGroup,
911
filterDeviceInventoryProjection,
1012
isDeviceClaimConflictReason,
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { describe, expect, test } from 'vitest';
2+
import type { ProviderDeviceInventorySource } from '@agent-device/contracts/device';
3+
import { createTestDeviceInventoryGateways } from '../inventory-gateways.fixtures.ts';
4+
5+
const scope = {
6+
signal: new AbortController().signal,
7+
diagnostics: { emit: () => {} },
8+
progress: { report: () => {} },
9+
} as const;
10+
11+
describe('test device inventory gateways', () => {
12+
test('a malformed provider outcome fails closed through the shared composer assertion', async () => {
13+
const gateways = createTestDeviceInventoryGateways({
14+
provider: { discover: async () => undefined } as unknown as ProviderDeviceInventorySource,
15+
});
16+
await expect(
17+
gateways.providerFirst.discover({ platform: 'android' }, scope),
18+
).rejects.toMatchObject({ details: { reason: 'provider_inventory_contract_violation' } });
19+
});
20+
21+
test('a declined provider falls through to the local inventory', async () => {
22+
const device = {
23+
platform: 'android' as const,
24+
id: 'emulator-5554',
25+
name: 'Pixel',
26+
kind: 'emulator' as const,
27+
booted: true,
28+
};
29+
const gateways = createTestDeviceInventoryGateways({
30+
provider: { discover: async () => ({ kind: 'declined' }) },
31+
local: async () => [device],
32+
});
33+
expect(await gateways.providerFirst.discover({ platform: 'android' }, scope)).toEqual([device]);
34+
});
35+
});

‎packages/device-selection/src/inventory-gateways.fixtures.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import {
2+
assertProviderOutcome,
23
filterDeviceInventoryProjection,
34
LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS,
45
projectProviderDeviceInventoryRequest,
@@ -43,6 +44,8 @@ async function discoverLocalFamily(
4344
): Promise<DeviceInfo[]> {
4445
scope.signal.throwIfAborted();
4546
const family: Platform = isApplePlatform(platform) ? 'apple' : platform;
47+
// `local` is a flat whole-inventory discoverer fanned out per family, so this filter is
48+
// the adapter to the per-family source contract, not a place production would assert.
4649
const devices = (await localDiscover(request)).filter((device) => device.platform === family);
4750
return filterDeviceInventoryProjection(devices, request);
4851
}
@@ -93,6 +96,7 @@ export function createTestDeviceInventoryGateways(
9396
scope.signal,
9497
);
9598
scope.signal.throwIfAborted();
99+
assertProviderOutcome(result);
96100
if (result.kind === 'inventory') {
97101
return {
98102
devices: filterDeviceInventoryProjection(

‎src/platform-runtime-device-inventory.ts‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import {
2+
assertProviderOutcome,
3+
assertSourceFamily,
24
filterDeviceInventoryProjection,
35
LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS,
46
projectProviderDeviceInventoryRequest,
@@ -24,7 +26,6 @@ import {
2426
type Platform,
2527
type PlatformSelector,
2628
} from '@agent-device/kernel/device';
27-
import { AppError } from '@agent-device/kernel/errors';
2829

2930
export function createComposedDeviceInventoryGateways(
3031
options: Readonly<{
@@ -210,26 +211,3 @@ async function discoverFamily(
210211
function familyForSelector(selector: PlatformSelector): Platform {
211212
return isApplePlatform(selector) ? 'apple' : selector;
212213
}
213-
214-
function assertSourceFamily(family: Platform, devices: readonly DeviceInfo[]): void {
215-
const outside = devices.find((device) => device.platform !== family);
216-
if (!outside) return;
217-
throw new AppError(
218-
'COMMAND_FAILED',
219-
`Platform inventory source ${family} returned a ${outside.platform} device.`,
220-
{ expectedFamily: family, actualFamily: outside.platform, deviceId: outside.id },
221-
);
222-
}
223-
224-
function assertProviderOutcome(
225-
value: unknown,
226-
): asserts value is Awaited<ReturnType<ProviderDeviceInventorySource['discover']>> {
227-
if (value !== null && typeof value === 'object') {
228-
const outcome = value as { kind?: unknown; devices?: unknown };
229-
if (outcome.kind === 'declined' && !('devices' in outcome)) return;
230-
if (outcome.kind === 'inventory' && Array.isArray(outcome.devices)) return;
231-
}
232-
throw new AppError('COMMAND_FAILED', 'Provider device inventory returned an invalid outcome.', {
233-
reason: 'provider_inventory_contract_violation',
234-
});
235-
}

0 commit comments

Comments
 (0)