refactor(contracts): consolidate per-domain defineUse wrappers into one neutral defineUse

[thymikee]

What changed

packages/contracts had four separate call sites re-deriving their own curried
alias of runtimeUse<PlatformRuntimeOperations>() with no distinguishing
information between them:

• network-runtime-plan.ts: defineNetworkUse
• logs-runtime-plan.ts: appLogUse
• screen-recording-runtime-plan.ts: defineScreenRecordingUse
• src/daemon/app-log-resource-recovery.ts: an inline
  runtimeUse<PlatformRuntimeOperations>()({...}) instantiation

Per ADR 0019 §9: "Use declarations share one neutral defineUse; per-domain
currying wrappers add a module per domain for no information."

This PR exports one neutral defineUse = runtimeUse<PlatformRuntimeOperations>()
from packages/contracts/src/platform-runtime.ts (the module where runtimeUse
already lives) and re-exports it from the @agent-device/contracts/platform
facade. Every runtime-use declaration in the four call sites above
(networkDumpUse, networkAdmissionUse, the app-log uses
appLogInspectUse/appLogDoctorUse/appLogStartUse/appLogAdmissionUse, the
screen-recording uses screenRecordingStartUse/screenRecordingRecoveryUse/
screenRecordingAdmissionUse, and appLogRecoveryUse) now builds through that
single defineUse export. The per-domain wrapper consts are deleted.

runtimeUse itself is untouched and stays exported — it's still the generic
primitive exercised directly by platform-runtime.test.ts against an
unrelated test Operations type.

Why this is behavior-neutral

This is a type-level refactor only:

• defineUse is exactly runtimeUse<PlatformRuntimeOperations>() — the same
  function the deleted wrappers each produced, with the same Operations type
  parameter. Every call site keeps its exact required/preferred argument
  list unchanged, so every produced RuntimeUse object is identical.
• No use declaration was added, removed, or had its required/preferred keys
  changed.
• 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
  (e.g. assert.deepEqual(networkDumpUse, { required: ['networkDump'], preferred: [] })).
  These pass unchanged after the refactor, so they double as the before/after
  regression proof that the produced objects didn't change.

Validation

• pnpm exec tsc -b packages/kernel packages/contracts — clean
• pnpm typecheck (full workspace + examples/sdk) — clean
• pnpm check:layering — 136/136 structural tests pass; type-cycle count
  unchanged at 46 (under the 47 baseline), confirming the new type-only
  platform-runtime.ts → platform-runtime-operations.ts import edge
  introduces no regression
• pnpm check:affected --run — 473 test files / 3939 tests passed, plus
  format, lint, layering, build/declarations, coverage-changed,
  integration-progress, replay-compat, and daemon-wire-compat checks

Part of #1739 (wave 0).

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.18 MB	2.18 MB	-18 B
JS gzip	712.0 kB	712.0 kB	+21 B
npm tarball	838.3 kB	838.3 kB	+17 B
npm unpacked	2.92 MB	2.92 MB	-18 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.0 ms	28.2 ms	+1.2 ms
CLI --help	66.1 ms	68.3 ms	+2.3 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/runtime2.js	0 B	+17 B
dist/src/sdk-batch-runner.js	-23 B	-14 B
dist/src/internal/daemon.js	+5 B	+1 B

[thymikee]

Exact-head review at ac3d8d31: not ready.

P2: packages/contracts/src/platform-runtime.ts now imports the concrete PlatformRuntimeOperations catalog solely to define defineUse, while platform-runtime-operations.ts already imports the generic runtime types from platform-runtime.ts. That creates an avoidable direct reverse type dependency and makes the lower generic primitive depend on its concrete aggregate catalog. The unchanged SCC file count does not prove this is harmless; it counts cycle members, not newly introduced back-edges. Define/export the one neutral defineUse alongside PlatformRuntimeOperations, then re-export it through the platform facade. This still satisfies ADR 0019 §9 while preserving one-way contract layering.

Otherwise the consolidation is behavior-neutral: every required/preferred literal is unchanged and the produced frozen use-object shapes remain identical. The iOS red check is the known unrelated simulator flake (automation-longpress reported visible=false); Android Smoke and Lint/Format were still pending when reviewed. No ready label applied.

[thymikee]

Fixed the P2: defineUse = runtimeUse<PlatformRuntimeOperations>() now lives in packages/contracts/src/platform-runtime-operations.ts, right next to the PlatformRuntimeOperations catalog it closes over, instead of in platform-runtime.ts. platform-runtime.ts no longer imports the concrete catalog — the generic runtimeUse primitive stays dependency-free of its concrete aggregate. All three per-domain call sites and the facade re-export now source defineUse from platform-runtime-operations.ts; @agent-device/contracts/platform still re-exports it, so no downstream import changed. Re-verified tsc (full workspace), check:layering, and check:affected --run clean at the new head.

🤖 Addressed by Claude Code

[thymikee]

Reviewed exact head 06cbc3ab. The prior dependency-cycle finding is resolved: defineUse now lives beside PlatformRuntimeOperations and depends one-way on the generic runtimeUse primitive; platform-runtime.ts no longer imports the concrete catalog. Use literals and frozen plan shapes are unchanged, and I found no new code issue. Code-review clean; final merge remains gated on the pending iOS/Fallow/CodeQL checks.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-11 16:06 UTC