refactor(capture-kit): move durable-capture resource mechanics out of the daemon (#2320)

* refactor(daemon): give durable capture a session-store port and a cleanup report

The durable-capture mechanics reached two daemon-owned authorities directly:
the concrete `SessionStore` class plus `SessionState`, and the admission
ledger, which `recoverFailedAdoption` called to block or clear a replacement
start. Both are daemon policy, so neither can travel with the mechanics.

Replace them with a two-member `DurableCaptureSessionStore<S>` port and a
session type parameter, and let the mechanics report what they observed —
`DurableCaptureCleanupOutcome` — while `createDurableCaptureResource` keeps
the clear/block decision and the reason text. Recovery takes the session
directory resolver from its caller instead of importing `safeSessionName`.

Splitting `DurableCaptureRecordDefinition` out of the definition says which
half needs a session at all: recovery, finish-recovered, and start preflight
terminalize a persisted record with no session in hand.

* refactor(capture-kit): move durable-capture resource mechanics out of the daemon

The daemon held two halves of one mechanism. capture-kit already owned the
durable-resource envelope, JSON, and descriptor codec; the fence, transition,
adoption, and recovery mechanics that operate on that envelope still sat in
`src/daemon` as eight files.

Move them behind the store port and cleanup report the previous commit
introduced, exposed through one new `@agent-device/capture-kit/durable-capture`
subpath — not the `.` index, which is the eager closure every platform runtime
imports. Admission, start preflight, runtime binding, the kind stamps, and the
composition root that wires the mechanics to the admission ledger stay daemon
policy.

The moved tests exercise the mechanics through a resource kind and session type
of their own, so what they prove is that the mechanics need neither the daemon's
closed kind set nor `SessionState`. The composition root keeps the admission
mapping the adoption test used to assert, now in
`durable-capture-resource.test.ts` where the ledger lives.

* refactor(capture-kit): drop the now-dead durable-envelope decoder re-export

The daemon's store and adoption modules were the `.` index's only production
consumers of `decodeDurableResourceEnvelope`; both now sit beside the encoder
inside capture-kit and import it directly.

* chore(gates): approve the durable-capture subpath over the domain-facade ceiling

* refactor(daemon): merge the duplicated durable-capture subpath imports

* refactor(capture-kit): keep the durable-capture subpath to its consumed surface

`tsc -b` cannot name the fixture spy's inferred type across the package
boundary, and five re-exported vocabulary types had no consumer.

* style(capture-kit): keep package specifiers ahead of relative imports

* test(daemon): make the failed-adoption clear mapping effective

The confirmed-cleanup test started with an unblocked ledger, so deleting
`clearUndurableCleanup` from the relocated composition mapping still left
`assertStartAllowed` green. Seed a block first, so the assertion is that the
mapping lifted it.

Author: thymikee

packages/capture-kit/package.json

@@ -14,6 +14,10 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./durable-capture": {
+      "types": "./src/durable-capture/index.ts",
+      "default": "./src/durable-capture/index.ts"
+    },
     "./durable-json": {
       "types": "./src/durable-json.ts",
       "default": "./src/durable-json.ts"

…urable-capture-resource-adoption.test.ts …kit/src/durable-capture/adoption.test.tssrc/daemon/__tests__/durable-capture-resource-adoption.test.ts renamed to packages/capture-kit/src/durable-capture/adoption.test.ts src/daemon/__tests__/durable-capture-resource-adoption.test.ts renamed to packages/capture-kit/src/durable-capture/adoption.test.ts

@@ -2,35 +2,41 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { expect, test } from 'vitest';
 import { AppError } from '@agent-device/kernel/errors';
+import { adoptStartedDurableCapture } from './adoption.ts';
 import {
   makeDurableCaptureContext,
   makeDurableCaptureStartResult,
-  testCaptureResource,
+  testCaptureDefinition,
   testCaptureStore,
-} from './durable-capture-resource.fixtures.ts';
+} from './durable-capture.fixtures.ts';
 
 test('canceled adoption cleans the pending handle before terminalizing its manifest', async () => {
   const context = makeDurableCaptureContext();
   const start = makeDurableCaptureStartResult(context);
   const cancellation = new AppError('CANCELED', 'request canceled');
 
   await expect(
-    testCaptureResource.adoptStarted({
-      ...context,
-      ...start,
-      throwIfCanceled: () => {
-        throw cancellation;
+    adoptStartedDurableCapture(
+      testCaptureDefinition,
+      {
+        ...context,
+        ...start,
+        throwIfCanceled: () => {
+          throw cancellation;
+        },
       },
-    }),
+      context.resourcePath,
+    ),
   ).rejects.toBe(cancellation);
   expect(start.forceCleanup).toHaveBeenCalledOnce();
   expect(testCaptureStore.read(context.resourcePath)).toMatchObject({
     status: 'decoded',
     envelope: { lifecycle: 'completed', metadata: { phase: 'completed' } },
   });
+  expect(context.reportUndurableCleanup).toHaveBeenCalledWith(context.device, { confirmed: true });
 });
 
-test('a failed terminal transition preserves the primary error and blocks replacement', async () => {
+test('a failed terminal transition preserves the primary error and reports it unconfirmed', async () => {
   const context = makeDurableCaptureContext();
   const start = makeDurableCaptureStartResult(context, {
     cleanup: { status: 'cleanup-pending', reason: 'cleanup-unconfirmed' },
@@ -40,18 +46,25 @@ test('a failed terminal transition preserves the primary error and blocks replac
 
   try {
     await expect(
-      testCaptureResource.adoptStarted({
-        ...context,
-        ...start,
-        throwIfCanceled: () => {
-          fs.chmodSync(resourceDir, 0o500);
-          throw primary;
+      adoptStartedDurableCapture(
+        testCaptureDefinition,
+        {
+          ...context,
+          ...start,
+          throwIfCanceled: () => {
+            fs.chmodSync(resourceDir, 0o500);
+            throw primary;
+          },
         },
-      }),
+        context.resourcePath,
+      ),
     ).rejects.toBe(primary);
   } finally {
     fs.chmodSync(resourceDir, 0o700);
   }
 
-  expect(() => context.admissionLedger.assertStartAllowed(context.device)).toThrow(/process-local/);
+  expect(context.reportUndurableCleanup).toHaveBeenCalledWith(context.device, {
+    confirmed: false,
+    reason: expect.stringMatching(/./),
+  });
 });

…mon/durable-capture-resource-adoption.ts …ture-kit/src/durable-capture/adoption.tssrc/daemon/durable-capture-resource-adoption.ts renamed to packages/capture-kit/src/durable-capture/adoption.ts src/daemon/durable-capture-resource-adoption.ts renamed to packages/capture-kit/src/durable-capture/adoption.ts

@@ -5,21 +5,19 @@ import {
   type RuntimeOwnerRef,
   runtimeOwnerKey,
 } from '@agent-device/contracts/platform-runtime';
-import {
-  createDurableResourceEnvelope,
-  decodeDurableResourceEnvelope,
-} from '@agent-device/capture-kit';
 import { deviceIdentity, sameDeviceIdentity, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
+import {
+  createDurableResourceEnvelope,
+  decodeDurableResourceEnvelope,
+} from '../durable-resource-envelope.ts';
 import type {
   AdoptStartedDurableCaptureParams,
+  DurableCaptureRecordDefinition,
   DurableCaptureResourceDefinition,
-} from './durable-capture-resource.ts';
-import {
-  capitalizeDurableCaptureLabel,
-  durableCaptureDiagnosticPrefix,
-} from './durable-capture-resource-labels.ts';
+} from './definition.ts';
+import { capitalizeDurableCaptureLabel, durableCaptureDiagnosticPrefix } from './labels.ts';
 
 type AdoptionState<H extends AsyncDisposable> =
   | { kind: 'pending' }
@@ -30,9 +28,10 @@ export async function adoptStartedDurableCapture<
   K extends string,
   H extends LiveResourceHandle<C>,
   C,
+  S,
 >(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
-  params: AdoptStartedDurableCaptureParams<K, H>,
+  definition: DurableCaptureResourceDefinition<K, H, C, S>,
+  params: AdoptStartedDurableCaptureParams<K, H, S>,
   resourcePath: string,
 ): Promise<void> {
   let state: AdoptionState<H> = { kind: 'pending' };
@@ -53,9 +52,9 @@ export async function adoptStartedDurableCapture<
   }
 }
 
-async function recoverFailedAdoption<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
-  params: AdoptStartedDurableCaptureParams<K, H>,
+async function recoverFailedAdoption<K extends string, H extends LiveResourceHandle<C>, C, S>(
+  definition: DurableCaptureResourceDefinition<K, H, C, S>,
+  params: AdoptStartedDurableCaptureParams<K, H, S>,
   resourcePath: string,
   state: AdoptionState<H>,
   primaryError: unknown,
@@ -69,23 +68,25 @@ async function recoverFailedAdoption<K extends string, H extends LiveResourceHan
     resourcePath,
     initialCleanupError,
   );
-  if ((!persisted && transition.cleanupError === undefined) || transition.confirmed) {
-    params.admissionLedger.clearUndurableCleanup(params.device);
-  } else {
-    params.admissionLedger.blockUndurableCleanup(
-      params.device,
-      transition.cleanupError instanceof Error
-        ? transition.cleanupError.message
-        : 'The durable cleanup transition could not be confirmed',
-    );
-  }
+  params.reportUndurableCleanup(
+    params.device,
+    (!persisted && transition.cleanupError === undefined) || transition.confirmed
+      ? { confirmed: true }
+      : {
+          confirmed: false,
+          reason:
+            transition.cleanupError instanceof Error
+              ? transition.cleanupError.message
+              : 'The durable cleanup transition could not be confirmed',
+        },
+  );
   if (transition.cleanupError !== undefined)
     emitCleanupDiagnostic(definition, params, primaryError, transition.cleanupError);
 }
 
-function confirmFailedAdoptionTransition<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
-  params: Pick<AdoptStartedDurableCaptureParams<K, H>, 'sessionName' | 'fence'>,
+function confirmFailedAdoptionTransition<K extends string, H extends LiveResourceHandle<C>, C, S>(
+  definition: DurableCaptureRecordDefinition<K, C>,
+  params: Pick<AdoptStartedDurableCaptureParams<K, H, S>, 'sessionName' | 'fence'>,
   resourcePath: string,
   cleanupError: unknown | undefined,
 ): { confirmed: boolean; cleanupError: unknown | undefined } {
@@ -108,8 +109,8 @@ function confirmFailedAdoptionTransition<K extends string, H extends LiveResourc
   }
 }
 
-async function disposeFailedAdoption<K extends string, H extends AsyncDisposable>(
-  params: AdoptStartedDurableCaptureParams<K, H>,
+async function disposeFailedAdoption<K extends string, H extends AsyncDisposable, S>(
+  params: AdoptStartedDurableCaptureParams<K, H, S>,
   state: AdoptionState<H>,
 ): Promise<unknown | undefined> {
   try {
@@ -121,9 +122,9 @@ async function disposeFailedAdoption<K extends string, H extends AsyncDisposable
   }
 }
 
-function persistRecoveryTombstone<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
-  params: AdoptStartedDurableCaptureParams<K, H>,
+function persistRecoveryTombstone<K extends string, H extends LiveResourceHandle<C>, C, S>(
+  definition: DurableCaptureRecordDefinition<K, C>,
+  params: AdoptStartedDurableCaptureParams<K, H, S>,
   resourcePath: string,
 ): boolean {
   try {
@@ -159,10 +160,10 @@ function persistRecoveryTombstone<K extends string, H extends LiveResourceHandle
   }
 }
 
-function createExpectedEnvelope<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
+function createExpectedEnvelope<K extends string, H extends LiveResourceHandle<C>, C, S>(
+  definition: DurableCaptureRecordDefinition<K, C>,
   params: Pick<
-    AdoptStartedDurableCaptureParams<K, H>,
+    AdoptStartedDurableCaptureParams<K, H, S>,
     'sessionName' | 'device' | 'owner' | 'fence'
   >,
   descriptor: DurableResourceEnvelope<K>['descriptor'],
@@ -179,10 +180,10 @@ function createExpectedEnvelope<K extends string, H extends LiveResourceHandle<C
   });
 }
 
-function validateStartedEnvelope<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
+function validateStartedEnvelope<K extends string, H extends LiveResourceHandle<C>, C, S>(
+  definition: DurableCaptureRecordDefinition<K, C>,
   params: Pick<
-    AdoptStartedDurableCaptureParams<K, H>,
+    AdoptStartedDurableCaptureParams<K, H, S>,
     'sessionName' | 'device' | 'owner' | 'fence' | 'envelope'
   >,
 ): DurableResourceEnvelope<K> {
@@ -224,8 +225,8 @@ function matchesAuthority(
   );
 }
 
-function confirmFailedAdoption<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
+function confirmFailedAdoption<K extends string, C>(
+  definition: DurableCaptureRecordDefinition<K, C>,
   resourcePath: string,
   expected: ResourceOwnershipFence,
   cleanupError: unknown | undefined,
@@ -249,9 +250,9 @@ function confirmFailedAdoption<K extends string, H extends LiveResourceHandle<C>
   return true;
 }
 
-function emitCleanupDiagnostic<K extends string, H extends LiveResourceHandle<C>, C>(
-  definition: DurableCaptureResourceDefinition<K, H, C>,
-  params: Pick<AdoptStartedDurableCaptureParams<K, H>, 'sessionName'>,
+function emitCleanupDiagnostic<K extends string, H extends AsyncDisposable, C, S>(
+  definition: DurableCaptureRecordDefinition<K, C>,
+  params: Pick<AdoptStartedDurableCaptureParams<K, H, S>, 'sessionName'>,
   primaryError: unknown,
   cleanupError: unknown,
 ): void {

packages/capture-kit/src/durable-capture/definition.ts

@@ -0,0 +1,74 @@
+import type { JsonObject } from '@agent-device/contracts/client';
+import type { DurableResourceEnvelope } from '@agent-device/contracts/durable-resource-envelope';
+import type { LiveResourceHandle } from '@agent-device/contracts/durable-resource';
+import type { PendingTransferGuard } from '@agent-device/contracts/async-lifecycle';
+import type {
+  ResourceOwnershipFence,
+  RuntimeOwnerRef,
+} from '@agent-device/contracts/platform-runtime';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { DurableCaptureResourceStore } from './store.ts';
+
+/**
+ * The whole of the session store these mechanics touch: where a session's records live, and
+ * how an updated session record is put back. The session type itself stays opaque — only a
+ * definition's own `sessionSlot` looks inside it.
+ */
+export type DurableCaptureSessionStore<S> = Readonly<{
+  set(name: string, session: S): void;
+  resolveSessionDir(name: string): string;
+}>;
+
+export type DurableCaptureSessionResource<K extends string, H extends AsyncDisposable> = Readonly<{
+  handle: H;
+  envelope: DurableResourceEnvelope<K>;
+}>;
+
+export type DurableCaptureSessionSlot<K extends string, H extends AsyncDisposable, S> = Readonly<{
+  read(session: S): DurableCaptureSessionResource<K, H> | undefined;
+  replace(session: S, resource: DurableCaptureSessionResource<K, H> | undefined): S;
+}>;
+
+/**
+ * The session-free half of a definition. Recovery reattaches and terminalizes a persisted
+ * record with no session in hand, so it names this and never the session type.
+ */
+export type DurableCaptureRecordDefinition<K extends string, C> = Readonly<{
+  resourceKind: K;
+  displayName: string;
+  store: DurableCaptureResourceStore<K>;
+  completionMetadata(result: C): JsonObject;
+  messages: Readonly<{
+    noActive: string;
+    cleanupPendingHint: string;
+  }>;
+}>;
+
+export type DurableCaptureResourceDefinition<
+  K extends string,
+  H extends LiveResourceHandle<C>,
+  C,
+  S,
+> = DurableCaptureRecordDefinition<K, C> &
+  Readonly<{ sessionSlot: DurableCaptureSessionSlot<K, H, S> }>;
+
+/**
+ * What the mechanics observed about a failed adoption's cleanup. Reporting it keeps the
+ * admission decision — block a replacement start, or clear an earlier block — with the caller.
+ */
+export type DurableCaptureCleanupOutcome =
+  | { confirmed: true }
+  | { confirmed: false; reason: string };
+
+export type AdoptStartedDurableCaptureParams<K extends string, H extends AsyncDisposable, S> = {
+  reportUndurableCleanup(device: DeviceInfo, outcome: DurableCaptureCleanupOutcome): void;
+  session: S;
+  sessionName: string;
+  sessionStore: DurableCaptureSessionStore<S>;
+  device: DeviceInfo;
+  owner: RuntimeOwnerRef;
+  fence: ResourceOwnershipFence;
+  pendingHandle: PendingTransferGuard<H>;
+  envelope: DurableResourceEnvelope<K>;
+  throwIfCanceled(): void;
+};