Skip to content

Commit f18f8b0

Browse files
authored
refactor(contracts): consolidate per-domain defineUse wrappers into one neutral defineUse (#1741)
* refactor(contracts): consolidate per-domain defineUse wrappers into one neutral defineUse ADR 0019 §9: use declarations share one neutral defineUse; per-domain currying wrappers around runtimeUse<PlatformRuntimeOperations>() add a module per domain for no information. network-runtime-plan.ts, logs-runtime-plan.ts, screen-recording-runtime-plan.ts, and app-log-resource-recovery.ts each re-derived their own curried alias (defineNetworkUse, appLogUse, defineScreenRecordingUse, and an inline instantiation) from the same generic factory with the same type parameter. Export defineUse = runtimeUse<PlatformRuntimeOperations>() once from platform-runtime.ts (where runtimeUse lives) and re-export it from the platform facade. Every runtime-use declaration (networkDumpUse, networkAdmissionUse, the app-log uses, the screen-recording uses, and appLogRecoveryUse) now builds through that single export; the per-domain wrappers are deleted. Type-level only: no required/preferred keys changed, and no use declaration was added, removed, or altered. Existing deepEqual assertions in network-runtime-plan.test.ts, logs-runtime-plan.test.ts, and screen-recording-runtime-plan.test.ts already pin every produced use object's exact {required, preferred} shape, so they double as the before/after regression proof that this refactor is behavior-neutral. Part of #1739 (wave 0). * fix(contracts): move defineUse into platform-runtime-operations.ts Review: defining defineUse in platform-runtime.ts required importing the concrete PlatformRuntimeOperations catalog into the generic runtimeUse primitive module, while platform-runtime-operations.ts already imports generic runtime types from platform-runtime.ts. That's an avoidable reverse type dependency — the lower generic primitive depended on its concrete aggregate catalog. The unchanged SCC file count didn't prove this harmless; it counts cycle members, not newly introduced back-edges. Move defineUse = runtimeUse<PlatformRuntimeOperations>() into platform-runtime-operations.ts, alongside PlatformRuntimeOperations. platform-runtime.ts no longer imports the concrete catalog. Re-export defineUse through the platform facade from its new source module; every call site keeps importing it from @agent-device/contracts/platform unchanged, and the three contracts-internal call sites now import it directly from platform-runtime-operations.ts. Validation: tsc (full workspace + examples/sdk), check:layering (136/136, type-cycle count unchanged at 46), and check:affected --run (473 files / 3939 tests) all clean at the new head.
1 parent bd233d5 commit f18f8b0

6 files changed

Lines changed: 29 additions & 28 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,7 @@ export type {
169169
NetworkRuntimePlan,
170170
NetworkRuntimePlanInput,
171171
} from '../network-runtime-plan.ts';
172+
export { defineUse } from '../platform-runtime-operations.ts';
172173
export type {
173174
PlatformRuntimeHost,
174175
PlatformRuntimeModule,

‎packages/contracts/src/logs-runtime-plan.ts‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
11
import { AppError } from '@agent-device/kernel/errors';
2-
import { runtimeUse } from './platform-runtime.ts';
3-
import type { PlatformRuntimeOperations } from './platform-runtime-operations.ts';
2+
import { defineUse } from './platform-runtime-operations.ts';
43

5-
const appLogUse = runtimeUse<PlatformRuntimeOperations>();
6-
7-
const appLogInspectUse = appLogUse({ required: ['appLogInspect'] });
8-
const appLogDoctorUse = appLogUse({ required: ['appLogInspect', 'appLogDoctor'] });
9-
const appLogStartUse = appLogUse({ required: ['appLogInspect', 'appLogStart'] });
4+
const appLogInspectUse = defineUse({ required: ['appLogInspect'] });
5+
const appLogDoctorUse = defineUse({ required: ['appLogInspect', 'appLogDoctor'] });
6+
const appLogStartUse = defineUse({ required: ['appLogInspect', 'appLogStart'] });
107

118
/** Fact-only admission probe; it is deliberately not an execution-plan variant. */
12-
export const appLogAdmissionUse = appLogUse({
9+
export const appLogAdmissionUse = defineUse({
1310
required: [],
1411
preferred: ['appLogInspect'],
1512
});

‎packages/contracts/src/network-runtime-plan.ts‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
import type { NetworkIncludeMode } from '@agent-device/kernel/contracts';
22
import { AppError } from '@agent-device/kernel/errors';
3-
import { runtimeUse } from './platform-runtime.ts';
4-
import type { PlatformRuntimeOperations } from './platform-runtime-operations.ts';
3+
import { defineUse } from './platform-runtime-operations.ts';
54

6-
const defineNetworkUse = runtimeUse<PlatformRuntimeOperations>();
7-
8-
export const networkDumpUse = defineNetworkUse({ required: ['networkDump'] });
5+
export const networkDumpUse = defineUse({ required: ['networkDump'] });
96

107
/** Fact-only capability projection; it is not an execution-plan variant. */
11-
export const networkAdmissionUse = defineNetworkUse({
8+
export const networkAdmissionUse = defineUse({
129
required: [],
1310
preferred: ['networkDump'],
1411
});

‎packages/contracts/src/platform-runtime-operations.ts‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,25 @@ import type { AppLogRuntimeHost, AppLogRuntimeOperations } from './app-log-runti
22
import type { NetworkRuntimeHost, NetworkRuntimeOperations } from './network-runtime.ts';
33
import type { ScreenRecordingRuntimeHost } from './screen-recording-runtime-host.ts';
44
import type { ScreenRecordingRuntimeOperations } from './screen-recording-runtime.ts';
5-
import type {
6-
DeviceRuntimeOwner,
7-
RuntimeOwnerRef,
8-
RuntimePlatformModule,
5+
import {
6+
runtimeUse,
7+
type DeviceRuntimeOwner,
8+
type RuntimeOwnerRef,
9+
type RuntimePlatformModule,
910
} from './platform-runtime.ts';
1011

1112
export type PlatformRuntimeOperations = AppLogRuntimeOperations &
1213
NetworkRuntimeOperations &
1314
ScreenRecordingRuntimeOperations;
1415

16+
/**
17+
* The one neutral runtime-use declaration every command domain shares (ADR 0019 §9): no
18+
* per-domain currying wrappers. Lives here, next to the concrete `PlatformRuntimeOperations`
19+
* catalog it closes over, so the generic `runtimeUse` primitive in `platform-runtime.ts`
20+
* never depends on it.
21+
*/
22+
export const defineUse = runtimeUse<PlatformRuntimeOperations>();
23+
1524
export type PlatformRuntimeHost = AppLogRuntimeHost &
1625
NetworkRuntimeHost &
1726
Readonly<{ screenRecording: ScreenRecordingRuntimeHost }>;

‎packages/contracts/src/screen-recording-runtime-plan.ts‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,17 @@
11
import { AppError } from '@agent-device/kernel/errors';
2-
import { runtimeUse } from './platform-runtime.ts';
3-
import type { PlatformRuntimeOperations } from './platform-runtime-operations.ts';
2+
import { defineUse } from './platform-runtime-operations.ts';
43
import type { RecordingScope } from './recording-scope.ts';
54

6-
const defineScreenRecordingUse = runtimeUse<PlatformRuntimeOperations>();
7-
8-
export const screenRecordingStartUse = defineScreenRecordingUse({
5+
export const screenRecordingStartUse = defineUse({
96
required: ['screenRecordingStart'],
107
});
11-
export const screenRecordingRecoveryUse = defineScreenRecordingUse({
8+
export const screenRecordingRecoveryUse = defineUse({
129
required: ['screenRecordingReattach', 'screenRecordingCleanup'],
1310
});
14-
const screenRecordingNoRuntimeUse = defineScreenRecordingUse({ required: [] });
11+
const screenRecordingNoRuntimeUse = defineUse({ required: [] });
1512

1613
/** Fact-only admission preserves start's preferred-fast-path semantics. */
17-
export const screenRecordingAdmissionUse = defineScreenRecordingUse({
14+
export const screenRecordingAdmissionUse = defineUse({
1815
required: [],
1916
preferred: ['screenRecordingStart'],
2017
});

‎src/daemon/app-log-resource-recovery.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import {
2+
defineUse,
23
narrowDeviceBinding,
3-
runtimeUse,
44
type AppLogCompletion,
55
type AppLogLiveHandle,
66
type DeviceRuntimeGateway,
@@ -16,7 +16,7 @@ import type {
1616
DurableCaptureRecoverySummary,
1717
} from './durable-capture-resource-recovery.ts';
1818

19-
const appLogRecoveryUse = runtimeUse<PlatformRuntimeOperations>()({
19+
const appLogRecoveryUse = defineUse({
2020
required: ['appLogReattach', 'appLogCleanup'],
2121
});
2222

0 commit comments

Comments
 (0)