refactor: extract durable capture kit

Author: thymikee

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

@@ -92,6 +92,15 @@ process primitives outside the shared host-command port. R11 applies these rules
 dynamic, and re-export edges; package-owned tests may import their own public façade. Contracts may
 depend on kernel vocabulary but never on concrete platform packages or daemon implementation types.
 
+Durable-capture mechanics shared by more than one implementation live in the private
+`@agent-device/capture-kit` workspace package, with the enforced direction
+`kernel < contracts < capture-kit < platform/provider/daemon`. Contracts retains pure vocabulary and
+plan models; process supervision, live-handle implementations, recovery helpers, runtime codecs, and
+capture parsers do not live there. `capture-kit` is a domain package for durable capture, not a generic
+platform-common package, and it preserves the package façades' implementation-lazy loading boundary.
+Its introduction carries the normal workspace-package compliance surface: `check:affected`
+selection, R11/R13 package enumeration, and the composite typecheck project list.
+
 Canonical family, `AppleOS`, public-leaf, and selector identity remain declared in
 `@agent-device/kernel/device`. Platform-module metadata references one canonical family; during
 coexistence the legacy plugin registry derives its family identity from the same declaration rather
@@ -330,11 +339,14 @@ but reattachment never scans telemetry to rebuild state.
 
 Every authoritative home exposes a deterministic facet-owned lookup or enumeration path after
 process loss. Its neutral record carries session/device identity, the exact runtime-owner reference,
-descriptor and metadata, an ownership/fence token, and a lifecycle state sufficient to distinguish
-starting, active, completing, completed, and cleanup-pending recovery. A new handle is not exposed
-until the persisted ownership fence is acquired. Every finish/cleanup attempt holds that ownership
-guard through destructive work and the persisted transition, or delegates to an operation that
-atomically enforces the token, so a prior owner cannot later terminate a transferred resource.
+descriptor and metadata, an ownership/fence token, and one of two persisted lifecycle states:
+`open` or `completed`. In-progress distinctions such as starting, active, completing, and
+cleanup-pending are phase metadata on the open record, not additional lifecycle states. The fence and
+the descriptor remain authoritative across every open phase; cleanup uncertainty therefore cannot be
+encoded as a terminal lifecycle. A new handle is not exposed until the persisted ownership fence is
+acquired. Every finish/cleanup attempt holds that ownership guard through destructive work and the
+persisted transition, or delegates to an operation that atomically enforces the token, so a prior
+owner cannot later terminate a transferred resource.
 
 Persisting a descriptor does not make external-resource start and descriptor write atomic. A
 platform whose native tool cannot close that crash window retains a platform-owned orphan marker or

package.json

@@ -130,7 +130,7 @@
     "check:affected:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/platform-packages.test.ts scripts/check-affected/run.test.ts",
     "check:coverage-changed": "node --experimental-strip-types scripts/coverage-changed/run.ts",
     "check:coverage-changed:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/coverage-changed/model.test.ts scripts/coverage-changed/run.test.ts",
-    "check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/model.test.ts scripts/layering/zone-policy.test.ts scripts/layering/daemon-modularity.test.ts scripts/layering/package-boundaries.test.ts scripts/layering/platform-package-policy.test.ts scripts/layering/platform-package-repository.test.ts scripts/layering/platform-package-source-policy.test.ts scripts/layering/device-inventory-cutover-policy.test.ts scripts/layering/logs-runtime-cutover-policy.test.ts scripts/layering/facade-exports.test.ts scripts/layering/bin-alias-fast-path.test.ts && node --experimental-strip-types scripts/layering/check.ts",
+    "check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/model.test.ts scripts/layering/zone-policy.test.ts scripts/layering/daemon-modularity.test.ts scripts/layering/package-boundaries.test.ts scripts/layering/platform-package-policy.test.ts scripts/layering/platform-package-repository.test.ts scripts/layering/platform-package-source-policy.test.ts scripts/layering/device-inventory-cutover-policy.test.ts scripts/layering/logs-runtime-cutover-policy.test.ts scripts/layering/contracts-implementation-policy.test.ts scripts/layering/facade-exports.test.ts scripts/layering/bin-alias-fast-path.test.ts && node --experimental-strip-types scripts/layering/check.ts",
     "depgraph": "node --experimental-strip-types scripts/depgraph/build.ts",
     "depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/affected.test.ts",
     "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
@@ -149,7 +149,7 @@
     "check:unit": "pnpm check:contention-retry && pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "pnpm check:mcp-metadata && pnpm package:npm",
-    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
+    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/capture-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
     "test-app:install": "pnpm install --dir examples/test-app",
     "test-app:start": "pnpm --dir examples/test-app start",
     "test-app:ios": "pnpm --dir examples/test-app ios",
@@ -252,6 +252,7 @@
     "yauzl": "^3.4.0"
   },
   "devDependencies": {
+    "@agent-device/capture-kit": "workspace:*",
     "@agent-device/ad-replay": "workspace:*",
     "@agent-device/ad-script": "workspace:*",
     "@agent-device/contracts": "workspace:*",

packages/capture-kit/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-device/capture-kit",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Private durable-capture mechanics shared by platform runtimes, providers, and daemon orchestration.",
+  "dependencies": {
+    "@agent-device/contracts": "workspace:*",
+    "@agent-device/kernel": "workspace:*"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  }
+}

…ontracts/src/app-log-live-handle-core.ts …s/capture-kit/src/app-log-live-handle.tspackages/contracts/src/app-log-live-handle-core.ts renamed to packages/capture-kit/src/app-log-live-handle.ts packages/contracts/src/app-log-live-handle-core.ts renamed to packages/capture-kit/src/app-log-live-handle.ts

@@ -1,10 +1,18 @@
 import { AppError } from '@agent-device/kernel/errors';
-import type {
-  AppLogCompletion,
-  AppLogLiveHandle,
-  AppLogLiveHandleImplementation,
-} from './app-log-runtime.ts';
-import { isConfirmedCleanup, type CleanupOutcome, type FinishOutcome } from './durable-resource.ts';
+import {
+  isConfirmedCleanup,
+  type AppLogCompletion,
+  type AppLogLiveHandle,
+  type AppLogLiveSnapshot,
+  type CleanupOutcome,
+  type FinishOutcome,
+} from '@agent-device/contracts/platform';
+
+type AppLogLiveHandleImplementation = Readonly<{
+  inspect(): AppLogLiveSnapshot;
+  finish(): Promise<FinishOutcome<AppLogCompletion>>;
+  forceCleanup(): Promise<CleanupOutcome>;
+}>;
 
 /** Internal idempotent adapter underlying the narrower public handle factories. */
 export function createAppLogLiveHandle(
@@ -25,6 +33,25 @@ export function createAppLogLiveHandle(
   });
 }
 
+/** Derives forced cleanup from an idempotent finish transaction. */
+export function createAppLogLiveHandleFromFinish(
+  implementation: Readonly<{
+    inspect(): AppLogLiveSnapshot;
+    finish(): Promise<FinishOutcome<AppLogCompletion>>;
+  }>,
+): AppLogLiveHandle {
+  return createAppLogLiveHandle({
+    inspect: implementation.inspect,
+    finish: implementation.finish,
+    forceCleanup: async () => {
+      const outcome = await implementation.finish();
+      return outcome.status === 'completed'
+        ? { status: 'cleaned' }
+        : { status: 'cleanup-pending', reason: outcome.reason, message: outcome.message };
+    },
+  });
+}
+
 function assertConfirmedCleanup(outcome: CleanupOutcome): void {
   if (isConfirmedCleanup(outcome)) return;
   throw new AppError(

…ontracts/src/app-log-pid-process.test.ts …ture-kit/src/app-log-pid-process.test.tspackages/contracts/src/app-log-pid-process.test.ts renamed to packages/capture-kit/src/app-log-pid-process.test.ts packages/contracts/src/app-log-pid-process.test.ts renamed to packages/capture-kit/src/app-log-pid-process.test.ts

@@ -3,7 +3,7 @@ import type {
   AppLogBackgroundProcess,
   AppLogOutputSink,
   AppLogRuntimeHost,
-} from './app-log-runtime.ts';
+} from '@agent-device/contracts/platform';
 import { createPidScopedAppLogProcess } from './app-log-pid-process.ts';
 
 describe('PID-scoped app-log process lifecycle', () => {

…ges/contracts/src/app-log-pid-process.ts …s/capture-kit/src/app-log-pid-process.tspackages/contracts/src/app-log-pid-process.ts renamed to packages/capture-kit/src/app-log-pid-process.ts packages/contracts/src/app-log-pid-process.ts renamed to packages/capture-kit/src/app-log-pid-process.ts

@@ -1,12 +1,12 @@
-import type { LogBackend } from './logs.ts';
+import type { LogBackend } from '@agent-device/contracts/observability';
 import type {
   AppLogBackgroundProcess,
   AppLogLiveHandle,
   AppLogLiveSnapshot,
   AppLogProcessStart,
   AppLogProcessCommand,
   AppLogRuntimeHost,
-} from './app-log-runtime.ts';
+} from '@agent-device/contracts/platform';
 import { createAppLogLiveHandleFromFinish } from './app-log-live-handle.ts';
 
 export type PidScopedAppLogProcessOptions = Readonly<{

…ontracts/src/app-log-pid-runtime.test.ts …ture-kit/src/app-log-pid-runtime.test.tspackages/contracts/src/app-log-pid-runtime.test.ts renamed to packages/capture-kit/src/app-log-pid-runtime.test.ts packages/contracts/src/app-log-pid-runtime.test.ts renamed to packages/capture-kit/src/app-log-pid-runtime.test.ts

@@ -1,12 +1,15 @@
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { expect, test, vi } from 'vitest';
+import {
+  type AppLogBackgroundProcess,
+  type AppLogRuntimeHost,
+  type DurableDescriptorCodec,
+} from '@agent-device/contracts/platform';
 import {
   createDurableResourceEnvelope,
   encodeDurableDescriptor,
 } from './durable-resource-envelope.ts';
-import type { AppLogBackgroundProcess, AppLogRuntimeHost } from './app-log-runtime.ts';
 import { createPidScopedAppLogRuntimeOwner } from './app-log-pid-runtime.ts';
-import type { DurableDescriptorCodec } from './durable-resource-envelope.ts';
 
 type TestDescriptor = Readonly<{
   transport: 'test-local' | 'test-provider';
@@ -74,7 +77,7 @@ test('PID-scoped runtime owner derives canonical artifacts and publishes one com
         },
         owner: selectedOwner,
         fence: input.fence,
-        lifecycle: 'active',
+        lifecycle: 'open',
         descriptor: encodeDurableDescriptor(descriptorCodec, descriptor),
       }),
   });

…ges/contracts/src/app-log-pid-runtime.ts …s/capture-kit/src/app-log-pid-runtime.tspackages/contracts/src/app-log-pid-runtime.ts renamed to packages/capture-kit/src/app-log-pid-runtime.ts packages/contracts/src/app-log-pid-runtime.ts renamed to packages/capture-kit/src/app-log-pid-runtime.ts

@@ -1,27 +1,24 @@
 import type { DeviceInfo, Platform } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import type { LogBackend } from './logs.ts';
-import type { HostCommandRequest } from './platform-runtime-host.ts';
 import type {
-  DeviceBinding,
-  DeviceRuntimeOwner,
-  RuntimeFacts,
-  RuntimeOwnerRef,
-} from './platform-runtime.ts';
-import { localRuntimeOwner, sameRuntimeOwner } from './platform-runtime.ts';
-import type {
-  AppLogDescriptorCodec,
-  AppLogDoctorResult,
   AppLogProcessCommand,
   AppLogProcessTransport,
   AppLogRuntimeHost,
   AppLogRuntimeOperations,
   AppLogSessionArtifacts,
   AppLogStartInput,
   AppLogStartResult,
-} from './app-log-runtime.ts';
+  DeviceBinding,
+  DeviceRuntimeOwner,
+  DurableDescriptorCodec,
+  DurableResourceEnvelope,
+  HostCommandRequest,
+  RuntimeFacts,
+  RuntimeOwnerRef,
+} from '@agent-device/contracts/platform';
+import { localRuntimeOwner, sameRuntimeOwner } from '@agent-device/contracts/platform';
+import type { LogBackend } from '@agent-device/contracts/observability';
 import { createAppLogRecoveryOperations, createAppLogStartResult } from './app-log-runtime.ts';
-import type { DurableResourceEnvelope } from './durable-resource-envelope.ts';
 import {
   cleanupManagedAppLogProcess,
   reattachCleanupOnlyAppLogProcess,
@@ -69,13 +66,13 @@ export type PidScopedAppLogRuntimeOptions<
   family: Family;
   backend: LogBackend;
   label: string;
-  codec: AppLogDescriptorCodec<Descriptor>;
+  codec: DurableDescriptorCodec<Descriptor, 'app-log'>;
   startUnavailableHint: string;
   cleanupFailureMessage: string;
   doctor(
     context: PidScopedAppLogRuntimeContext,
     appBundleId: string | undefined,
-  ): Promise<AppLogDoctorResult>;
+  ): ReturnType<AppLogRuntimeOperations['appLogDoctor']>;
   validateStart?(context: PidScopedAppLogStartContext): void;
   process(context: PidScopedAppLogStartContext): Promise<PidScopedAppLogProcessPlan>;
   descriptor(input: {

packages/contracts/src/app-log-probe.ts packages/capture-kit/src/app-log-probe.tspackages/contracts/src/app-log-probe.ts renamed to packages/capture-kit/src/app-log-probe.ts

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
 import { test, vi } from 'vitest';
-import type { AppLogProcessMarkerReadOutcome, AppLogProcessOwnership } from './app-log-runtime.ts';
+import type {
+  AppLogProcessMarkerReadOutcome,
+  AppLogProcessOwnership,
+} from '@agent-device/contracts/platform';
 import {
   cleanupManagedAppLogProcess,
   reattachCleanupOnlyAppLogProcess,