@yolk-sdk/harness 0.1.0-canary.100

package/dist/store.mjs

@@ -0,0 +1,98 @@
+import { Context, Effect, Layer, Ref, Semaphore } from "effect";
+//#region src/store.ts
+const emptySnapshot = {
+	claimed: [],
+	resumes: []
+};
+const snapshotFromMemory = (memory) => ({
+	claimed: [...memory.claimed],
+	resumes: [...memory.resumes.entries()]
+});
+const memoryFromSnapshot = (snapshot) => ({
+	claimed: new Set(snapshot.claimed),
+	resumes: new Map(snapshot.resumes)
+});
+var RunStore = class RunStore extends Context.Service()("@yolk-sdk/harness/RunStore") {
+	/**
+	* Canonical owning layer for snapshot-backed claims. Each call builds a fresh layer so
+	* composed harnesses never share `Ref` state or the snapshot lock across factory calls.
+	*/
+	static snapshotLayer = (options) => Layer.effect(this, Effect.gen(function* () {
+		const loaded = yield* options.load;
+		const memory = yield* Ref.make(memoryFromSnapshot(loaded ?? emptySnapshot));
+		const lock = yield* Semaphore.make(1);
+		const mutate = (effect) => Effect.uninterruptibleMask((restore) => restore(lock.take(1)).pipe(Effect.flatMap(() => effect.pipe(Effect.ensuring(lock.release(1))))));
+		const commit = (next) => options.save(snapshotFromMemory(next)).pipe(Effect.flatMap(() => Ref.set(memory, next)));
+		return RunStore.of({
+			claim: (runId) => mutate(Effect.gen(function* () {
+				const current = yield* Ref.get(memory);
+				yield* commit({
+					claimed: new Set(current.claimed).add(runId),
+					resumes: current.resumes
+				});
+			})),
+			release: (runId) => mutate(Effect.gen(function* () {
+				const current = yield* Ref.get(memory);
+				const claimed = new Set(current.claimed);
+				claimed.delete(runId);
+				const resumes = new Map(current.resumes);
+				resumes.delete(runId);
+				yield* commit({
+					claimed,
+					resumes
+				});
+			})),
+			isClaimed: (runId) => Ref.get(memory).pipe(Effect.map((current) => current.claimed.has(runId))),
+			claimed: Ref.get(memory).pipe(Effect.map((current) => new Set(current.claimed))),
+			incrementResumeCount: (runId) => mutate(Effect.gen(function* () {
+				const current = yield* Ref.get(memory);
+				const nextCount = (current.resumes.get(runId) ?? 0) + 1;
+				const resumes = new Map(current.resumes);
+				resumes.set(runId, nextCount);
+				yield* commit({
+					claimed: current.claimed,
+					resumes
+				});
+				return nextCount;
+			})),
+			resumeCount: (runId) => Ref.get(memory).pipe(Effect.map((current) => current.resumes.get(runId) ?? 0))
+		});
+	}));
+	/**
+	* Canonical owning layer for process-local claims. Each call builds a fresh layer so
+	* composed harnesses never share `Ref` state across factory calls.
+	*/
+	static inMemoryLayer = () => Layer.effect(this, Effect.gen(function* () {
+		const claimed = yield* Ref.make(/* @__PURE__ */ new Set());
+		const resumes = yield* Ref.make(/* @__PURE__ */ new Map());
+		return RunStore.of({
+			claim: (runId) => Ref.update(claimed, (current) => new Set(current).add(runId)),
+			release: (runId) => Effect.zip(Ref.update(claimed, (current) => {
+				const next = new Set(current);
+				next.delete(runId);
+				return next;
+			}), Ref.update(resumes, (current) => {
+				const next = new Map(current);
+				next.delete(runId);
+				return next;
+			})).pipe(Effect.asVoid),
+			isClaimed: (runId) => Ref.get(claimed).pipe(Effect.map((current) => current.has(runId))),
+			claimed: Ref.get(claimed).pipe(Effect.map((current) => new Set(current))),
+			incrementResumeCount: (runId) => Ref.modify(resumes, (current) => {
+				const nextCount = (current.get(runId) ?? 0) + 1;
+				const next = new Map(current);
+				next.set(runId, nextCount);
+				return [nextCount, next];
+			}),
+			resumeCount: (runId) => Ref.get(resumes).pipe(Effect.map((current) => current.get(runId) ?? 0))
+		});
+	}));
+};
+/** Backward-compatible delegation to {@link RunStore.snapshotLayer}. */
+const makeSnapshotRunStoreLayer = (options) => RunStore.snapshotLayer(options);
+/** Backward-compatible delegation to {@link RunStore.inMemoryLayer}. */
+const makeInMemoryRunStoreLayer = () => RunStore.inMemoryLayer();
+//#endregion
+export { RunStore, makeInMemoryRunStoreLayer, makeSnapshotRunStoreLayer };
+
+//# sourceMappingURL=store.mjs.map

package/dist/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","names":[],"sources":["../src/store.ts"],"sourcesContent":["import { Context, Effect, Layer, Ref, Semaphore } from 'effect'\n\nexport type RunStoreApi = {\n  readonly claim: (runId: string) => Effect.Effect<void>\n  readonly release: (runId: string) => Effect.Effect<void>\n  readonly isClaimed: (runId: string) => Effect.Effect<boolean>\n  readonly claimed: Effect.Effect<ReadonlySet<string>>\n  readonly incrementResumeCount: (runId: string) => Effect.Effect<number>\n  readonly resumeCount: (runId: string) => Effect.Effect<number>\n}\n\nexport type SnapshotRunStoreOptions = {\n  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>\n  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>\n}\n\nexport type DurableRunStoreSnapshot = {\n  readonly claimed: ReadonlyArray<string>\n  readonly resumes: ReadonlyArray<readonly [string, number]>\n}\n\ntype MemorySnapshot = {\n  readonly claimed: ReadonlySet<string>\n  readonly resumes: ReadonlyMap<string, number>\n}\n\nconst emptySnapshot: DurableRunStoreSnapshot = {\n  claimed: [],\n  resumes: []\n}\n\nconst snapshotFromMemory = (memory: MemorySnapshot): DurableRunStoreSnapshot => ({\n  claimed: [...memory.claimed],\n  resumes: [...memory.resumes.entries()]\n})\n\nconst memoryFromSnapshot = (snapshot: DurableRunStoreSnapshot): MemorySnapshot => ({\n  claimed: new Set(snapshot.claimed),\n  resumes: new Map(snapshot.resumes)\n})\n\nexport class RunStore extends Context.Service<RunStore, RunStoreApi>()(\n  '@yolk-sdk/harness/RunStore'\n) {\n  /**\n   * Canonical owning layer for snapshot-backed claims. Each call builds a fresh layer so\n   * composed harnesses never share `Ref` state or the snapshot lock across factory calls.\n   */\n  static snapshotLayer = (options: SnapshotRunStoreOptions): Layer.Layer<RunStore> =>\n    Layer.effect(\n      this,\n      Effect.gen(function* () {\n        const loaded = yield* options.load\n        const memory = yield* Ref.make(memoryFromSnapshot(loaded ?? emptySnapshot))\n        const lock = yield* Semaphore.make(1)\n\n        const mutate = <A, E, R>(effect: Effect.Effect<A, E, R>) =>\n          Effect.uninterruptibleMask(restore =>\n            restore(lock.take(1)).pipe(\n              Effect.flatMap(() => effect.pipe(Effect.ensuring(lock.release(1))))\n            )\n          )\n\n        const commit = (next: MemorySnapshot) =>\n          options.save(snapshotFromMemory(next)).pipe(Effect.flatMap(() => Ref.set(memory, next)))\n\n        return RunStore.of({\n          claim: runId =>\n            mutate(\n              Effect.gen(function* () {\n                const current = yield* Ref.get(memory)\n                yield* commit({\n                  claimed: new Set(current.claimed).add(runId),\n                  resumes: current.resumes\n                })\n              })\n            ),\n          release: runId =>\n            mutate(\n              Effect.gen(function* () {\n                const current = yield* Ref.get(memory)\n                const claimed = new Set(current.claimed)\n                claimed.delete(runId)\n                const resumes = new Map(current.resumes)\n                resumes.delete(runId)\n                yield* commit({ claimed, resumes })\n              })\n            ),\n          isClaimed: runId =>\n            Ref.get(memory).pipe(Effect.map(current => current.claimed.has(runId))),\n          claimed: Ref.get(memory).pipe(Effect.map(current => new Set(current.claimed))),\n          incrementResumeCount: runId =>\n            mutate(\n              Effect.gen(function* () {\n                const current = yield* Ref.get(memory)\n                const nextCount = (current.resumes.get(runId) ?? 0) + 1\n                const resumes = new Map(current.resumes)\n                resumes.set(runId, nextCount)\n                yield* commit({ claimed: current.claimed, resumes })\n\n                return nextCount\n              })\n            ),\n          resumeCount: runId =>\n            Ref.get(memory).pipe(Effect.map(current => current.resumes.get(runId) ?? 0))\n        })\n      })\n    )\n\n  /**\n   * Canonical owning layer for process-local claims. Each call builds a fresh layer so\n   * composed harnesses never share `Ref` state across factory calls.\n   */\n  static inMemoryLayer = (): Layer.Layer<RunStore> =>\n    Layer.effect(\n      this,\n      Effect.gen(function* () {\n        const claimed = yield* Ref.make(new Set<string>())\n        const resumes = yield* Ref.make(new Map<string, number>())\n\n        return RunStore.of({\n          claim: runId => Ref.update(claimed, current => new Set(current).add(runId)),\n          release: runId =>\n            Effect.zip(\n              Ref.update(claimed, current => {\n                const next = new Set(current)\n                next.delete(runId)\n\n                return next\n              }),\n              Ref.update(resumes, current => {\n                const next = new Map(current)\n                next.delete(runId)\n\n                return next\n              })\n            ).pipe(Effect.asVoid),\n          isClaimed: runId => Ref.get(claimed).pipe(Effect.map(current => current.has(runId))),\n          claimed: Ref.get(claimed).pipe(Effect.map(current => new Set(current))),\n          incrementResumeCount: runId =>\n            Ref.modify(resumes, current => {\n              const nextCount = (current.get(runId) ?? 0) + 1\n              const next = new Map(current)\n              next.set(runId, nextCount)\n\n              return [nextCount, next] as const\n            }),\n          resumeCount: runId =>\n            Ref.get(resumes).pipe(Effect.map(current => current.get(runId) ?? 0))\n        })\n      })\n    )\n}\n\n/** Backward-compatible delegation to {@link RunStore.snapshotLayer}. */\nexport const makeSnapshotRunStoreLayer = (\n  options: SnapshotRunStoreOptions\n): Layer.Layer<RunStore> => RunStore.snapshotLayer(options)\n\n/** Backward-compatible delegation to {@link RunStore.inMemoryLayer}. */\nexport const makeInMemoryRunStoreLayer = (): Layer.Layer<RunStore> => RunStore.inMemoryLayer()\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@yolk-sdk/harness",
+  "version": "0.1.0-canary.100",
+  "description": "Domain-free agent run lifecycle: coordinator, store, inbox, and pluggable drivers.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/harness"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "agent",
+    "harness",
+    "lifecycle",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./coordinator": {
+      "types": "./dist/coordinator.d.mts",
+      "import": "./dist/coordinator.mjs",
+      "default": "./dist/coordinator.mjs"
+    },
+    "./store": {
+      "types": "./dist/store.d.mts",
+      "import": "./dist/store.mjs",
+      "default": "./dist/store.mjs"
+    },
+    "./inbox": {
+      "types": "./dist/inbox.d.mts",
+      "import": "./dist/inbox.mjs",
+      "default": "./dist/inbox.mjs"
+    },
+    "./driver": {
+      "types": "./dist/driver.d.mts",
+      "import": "./dist/driver.mjs",
+      "default": "./dist/driver.mjs"
+    },
+    "./driver/memory": {
+      "types": "./dist/driver/memory.d.mts",
+      "import": "./dist/driver/memory.mjs",
+      "default": "./dist/driver/memory.mjs"
+    },
+    "./driver/durable-object": {
+      "types": "./dist/driver/durable-object.d.mts",
+      "import": "./dist/driver/durable-object.mjs",
+      "default": "./dist/driver/durable-object.mjs"
+    },
+    "./outcome": {
+      "types": "./dist/outcome.d.mts",
+      "import": "./dist/outcome.mjs",
+      "default": "./dist/outcome.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "effect": "4.0.0",
+    "@yolk-sdk/agent": "^0.1.0-canary.100"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/coordinator.ts

@@ -0,0 +1,355 @@
+/**
+ * Process-local run coordinator.
+ *
+ * Port of OpenCode v2 `SessionRunCoordinator` (MIT): one busy period per key,
+ * a doorbell that coalesces wakes, and interrupt that claims pending wakes so a
+ * dead intent cannot restart. Steering lands at the next drain boundary.
+ *
+ * @see https://github.com/sst/opencode (packages/core/src/session/run-coordinator.ts)
+ */
+import { Cause, Context, Deferred, Effect, Exit, Fiber, FiberSet, Layer } from 'effect'
+import type { Scope } from 'effect'
+import { StopReceipt as stopReceipt } from './outcome-constructors-internal.ts'
+import { RunStore } from './store.ts'
+
+// Private settlement receipt: succeed the Deferred with Exit as a value so
+// interrupt fan-out does not skip Effect 4.0.0-beta.80 Deferred listeners.
+// Public waiters flatten that Exit; this is not a global Deferred fix.
+const awaitDone = <E>(done: Deferred.Deferred<Exit.Exit<void, E>>): Effect.Effect<void, E> =>
+  Deferred.await(done).pipe(Effect.flatMap(exit => exit))
+
+/** `"input"` subsumes `"steer"` when coalescing wakes. */
+export type Promotable = 'input' | 'steer'
+
+/** Shutdown retains the claim; explicit user stop releases it after settlement. */
+export type InterruptReason = 'user' | 'shutdown'
+
+export type CapturedRun<E> =
+  | { readonly _tag: 'Started'; readonly join: Effect.Effect<void, E> }
+  | { readonly _tag: 'Joined'; readonly join: Effect.Effect<void, E> }
+  | { readonly _tag: 'Stopping'; readonly awaitSettlement: Effect.Effect<void> }
+
+export type StopReceipt =
+  | { readonly _tag: 'Idle' }
+  | { readonly _tag: 'Interrupted' }
+  | { readonly _tag: 'LiveStopping' }
+  | { readonly _tag: 'Settling' }
+
+export type Coordinator<Key, E, Reason = never> = {
+  readonly active: Effect.Effect<ReadonlySet<Key>>
+  readonly isActive: (key: Key) => Effect.Effect<boolean>
+  /** Starts an execution while idle, or joins the active execution. */
+  readonly run: (key: Key) => Effect.Effect<void, E>
+  /**
+   * Captures a run waiter without awaiting settlement.
+   * Idle starts force=true (`Started`); an active owner is joined (`Joined`),
+   * including during natural settlement. A stopping owner yields `Stopping` with a
+   * settlement waiter and no start.
+   */
+  readonly captureRun: (key: Key) => Effect.Effect<CapturedRun<E>>
+  /** Rings the doorbell: idle starts; active drains again before settling. */
+  readonly wake: (key: Key, scope?: Promotable) => Effect.Effect<void>
+  /**
+   * Stops the active execution and clears its doorbell. No-op when idle.
+   * Resolves once the interruption request is delivered, not when cleanup settles.
+   * First accepted `reason` is kept; use `terminalStop` to escalate.
+   */
+  readonly interrupt: (
+    key: Key,
+    reason?: Reason,
+    options?: { readonly awaitSettlement?: boolean }
+  ) => Effect.Effect<boolean>
+  /**
+   * Terminal stop receipt. Always clears pendingWake. Settling means the owner
+   * is already gone and the settled callback is chosen; Driver may release the
+   * claim under the Inbox gate. LiveStopping/Interrupted leave release to that
+   * owner's future settled callback. LiveStopping joins the same outstanding
+   * interruption request rather than forking a second one.
+   */
+  readonly terminalStop: (key: Key, reason: Reason) => Effect.Effect<StopReceipt>
+  /** Resolves once no execution is active. Never starts work. */
+  readonly awaitIdle: (key: Key) => Effect.Effect<void>
+}
+
+type Execution<E, Reason> = {
+  readonly done: Deferred.Deferred<Exit.Exit<void, E>>
+  owner?: Fiber.Fiber<void>
+  request?: Fiber.Fiber<void>
+  scope: Promotable
+  pendingWake?: Promotable
+  stopping: boolean
+  interruptionReason?: Reason
+}
+
+const widerScope = (current: Promotable | undefined, next: Promotable): Promotable =>
+  current === 'input' || next === 'input' ? 'input' : 'steer'
+
+export const makeCoordinator = <Key, E, Reason = never>(options: {
+  readonly drain: (key: Key, force: boolean, scope: Promotable) => Effect.Effect<void, E>
+  readonly started?: (key: Key) => Effect.Effect<void>
+  readonly settled?: (key: Key, exit: Exit.Exit<void, E>, reason?: Reason) => Effect.Effect<void>
+}): Effect.Effect<Coordinator<Key, E, Reason>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const executions = new Map<Key, Execution<E, Reason>>()
+    const fork = yield* FiberSet.makeRuntime<never, void, never>()
+
+    const loop = (
+      key: Key,
+      execution: Execution<E, Reason>,
+      force: boolean
+    ): Effect.Effect<void, E> =>
+      Effect.suspend(() => {
+        if (execution.stopping) return Effect.void
+
+        return options.drain(key, force, execution.scope)
+      }).pipe(
+        Effect.andThen(
+          Effect.suspend(() => {
+            if (execution.stopping || execution.pendingWake === undefined) return Effect.void
+            execution.scope = execution.pendingWake
+            execution.pendingWake = undefined
+
+            return Effect.yieldNow.pipe(Effect.andThen(loop(key, execution, false)))
+          })
+        )
+      )
+
+    const settle = (key: Key, execution: Execution<E, Reason>, exit: Exit.Exit<void, E>) => {
+      if (execution.pendingWake !== undefined) start(key, false, execution.pendingWake)
+      else executions.delete(key)
+
+      return Deferred.succeed(execution.done, exit).pipe(Effect.asVoid)
+    }
+
+    const start = (key: Key, force: boolean, scope: Promotable) => {
+      const execution: Execution<E, Reason> = {
+        done: Deferred.makeUnsafe<Exit.Exit<void, E>>(),
+        scope,
+        stopping: false
+      }
+
+      executions.set(key, execution)
+      execution.owner = fork(
+        Effect.yieldNow.pipe(
+          Effect.andThen(
+            Effect.uninterruptible(Effect.suspend(() => options.started?.(key) ?? Effect.void))
+          ),
+          Effect.andThen(loop(key, execution, force)),
+          Effect.onExit(exit =>
+            Effect.suspend(() => {
+              execution.owner = undefined
+
+              return options.settled?.(key, exit, execution.interruptionReason) ?? Effect.void
+            })
+          ),
+          Effect.onExit(exit => settle(key, execution, exit)),
+          Effect.exit,
+          Effect.asVoid
+        )
+      )
+
+      return execution
+    }
+
+    const forkInterruptionRequest = (owner: Fiber.Fiber<void>): Fiber.Fiber<void> =>
+      fork(Effect.yieldNow.pipe(Effect.andThen(Effect.sync(() => owner.interruptUnsafe()))))
+
+    const interruptNow = (key: Key, reason?: Reason): Effect.Effect<boolean> =>
+      Effect.suspend(() => {
+        const execution = executions.get(key)
+
+        if (execution === undefined || execution.stopping) return Effect.succeed(false)
+
+        if (execution.owner === undefined) {
+          execution.pendingWake = undefined
+
+          return Effect.succeed(false)
+        }
+
+        const owner = execution.owner
+        execution.stopping = true
+        execution.pendingWake = undefined
+        execution.interruptionReason = reason
+        // Capture the exact old owner and fork the request in this same lazy
+        // transition so cancellation cannot leave stopping=true with no request.
+        // Initial yield breaks owner -> resumed caller -> owner reentrancy.
+        // Join the request fiber only; interruptUnsafe may run interruptible
+        // finalizers inline until they suspend. Do not await owner settlement.
+        const request = forkInterruptionRequest(owner)
+        execution.request = request
+
+        return Fiber.join(request).pipe(Effect.as(true))
+      })
+
+    const awaitIdle = (key: Key): Effect.Effect<void> =>
+      Effect.suspend(() => {
+        const execution = executions.get(key)
+
+        if (execution === undefined) return Effect.void
+
+        return awaitDone(execution.done).pipe(Effect.ignoreCause, Effect.andThen(awaitIdle(key)))
+      })
+
+    return {
+      active: Effect.sync(() => new Set(executions.keys())),
+      isActive: key => Effect.sync(() => executions.has(key)),
+      run: key =>
+        Effect.suspend(() => {
+          const execution = executions.get(key)
+
+          if (execution === undefined) return awaitDone(start(key, true, 'input').done)
+
+          if (!execution.stopping) return awaitDone(execution.done)
+
+          return awaitDone(execution.done).pipe(
+            Effect.ignoreCause,
+            Effect.andThen(
+              Effect.suspend(() => {
+                const next = executions.get(key)
+
+                return next === undefined
+                  ? awaitDone(start(key, true, 'input').done)
+                  : awaitDone(next.done)
+              })
+            )
+          )
+        }),
+      captureRun: key =>
+        Effect.sync(() => {
+          const execution = executions.get(key)
+
+          if (execution === undefined) {
+            const started = start(key, true, 'input')
+
+            return { _tag: 'Started' as const, join: awaitDone(started.done) }
+          }
+
+          if (!execution.stopping) {
+            return { _tag: 'Joined' as const, join: awaitDone(execution.done) }
+          }
+
+          return {
+            _tag: 'Stopping' as const,
+            awaitSettlement: awaitDone(execution.done).pipe(Effect.ignoreCause)
+          }
+        }),
+      wake: (key, scope = 'input') =>
+        Effect.sync(() => {
+          const execution = executions.get(key)
+
+          if (execution !== undefined) {
+            execution.pendingWake = widerScope(execution.pendingWake, scope)
+
+            return
+          }
+
+          start(key, false, scope)
+        }),
+      interrupt: (key, reason, options) =>
+        Effect.suspend(() => {
+          const execution = executions.get(key)
+
+          return interruptNow(key, reason).pipe(
+            Effect.tap(() =>
+              options?.awaitSettlement === true && execution !== undefined
+                ? awaitDone(execution.done).pipe(Effect.ignoreCause)
+                : Effect.void
+            )
+          )
+        }),
+      terminalStop: (key, reason) =>
+        Effect.suspend((): Effect.Effect<StopReceipt> => {
+          const execution = executions.get(key)
+
+          if (execution === undefined) return Effect.succeed(stopReceipt.Idle())
+          execution.pendingWake = undefined
+
+          if (execution.owner === undefined) {
+            execution.stopping = true
+
+            return Effect.succeed(stopReceipt.Settling())
+          }
+
+          execution.interruptionReason = reason
+
+          if (execution.stopping) {
+            const request = execution.request
+
+            return request === undefined
+              ? Effect.succeed(stopReceipt.LiveStopping())
+              : Fiber.join(request).pipe(Effect.as(stopReceipt.LiveStopping()))
+          }
+
+          const owner = execution.owner
+          execution.stopping = true
+          const request = forkInterruptionRequest(owner)
+          execution.request = request
+
+          return Fiber.join(request).pipe(Effect.as(stopReceipt.Interrupted()))
+        }),
+      awaitIdle
+    }
+  })
+
+/** Owning coordinator layer, with per-acquisition claim receipts and settlement policy. */
+export class RunCoordinator extends Context.Service<
+  RunCoordinator,
+  Coordinator<string, never, InterruptReason>
+>()('@yolk-sdk/harness/RunCoordinator') {
+  static layer = (options?: {
+    readonly drain?: (runId: string, force: boolean, scope: Promotable) => Effect.Effect<void>
+  }): Layer.Layer<RunCoordinator, never, RunStore> =>
+    Layer.effect(
+      this,
+      Effect.gen(function* () {
+        const store = yield* RunStore
+        const drain = options?.drain ?? ((_runId, _force, _scope) => Effect.void)
+        const acquired = new Set<string>()
+
+        return yield* makeCoordinator<string, never, InterruptReason>({
+          drain,
+          started: runId =>
+            store.claim(runId).pipe(
+              Effect.tap(() =>
+                Effect.sync(() => {
+                  acquired.add(runId)
+                })
+              )
+            ),
+          settled: (runId, exit, reason) =>
+            Effect.suspend(() => {
+              const owned = acquired.delete(runId)
+
+              if (
+                owned &&
+                (reason === 'user' || (reason === undefined && !Exit.hasInterrupts(exit)))
+              ) {
+                return store.release(runId)
+              }
+
+              // Acquisition receipt guards automatic failed-start settlement only.
+              // Explicit user-terminal authority still releases a leftover claim
+              // after this owner has actually settled, matching Idle/Settling stop.
+              if (reason === 'user' && !owned) {
+                return store
+                  .isClaimed(runId)
+                  .pipe(Effect.flatMap(claimed => (claimed ? store.release(runId) : Effect.void)))
+              }
+
+              return Effect.void
+            }).pipe(
+              Effect.exit,
+              Effect.flatMap(settledExit => {
+                if (Exit.isSuccess(settledExit)) return Effect.void
+
+                return Effect.failCause(
+                  Exit.isFailure(exit)
+                    ? Cause.combine(exit.cause, settledExit.cause)
+                    : settledExit.cause
+                )
+              })
+            )
+        })
+      })
+    )
+}

package/src/driver/durable-object.ts

@@ -0,0 +1,28 @@
+import { Layer } from 'effect'
+import type { Effect } from 'effect'
+import { Driver, type Drain, type InvalidMaxResumeAttempts } from '../driver.ts'
+import { Inbox } from '../inbox.ts'
+import { RunStore, type DurableRunStoreSnapshot } from '../store.ts'
+
+export type { DurableRunStoreSnapshot }
+
+type DurableObjectDriverBase = {
+  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>
+  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>
+  readonly drain?: Drain
+}
+
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: undefined }
+): Layer.Layer<Driver | RunStore | Inbox>
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: number }
+): Layer.Layer<Driver | RunStore | Inbox, InvalidMaxResumeAttempts>
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: number }
+) {
+  return Driver.coordinatedLayer(options).pipe(
+    Layer.provideMerge(RunStore.snapshotLayer(options)),
+    Layer.provideMerge(Inbox.layer())
+  )
+}

package/src/driver/memory.ts

@@ -0,0 +1,39 @@
+import { Layer } from 'effect'
+import {
+  Driver,
+  type Drain,
+  type DriverLayerOptions,
+  type InvalidMaxResumeAttempts
+} from '../driver.ts'
+import { Inbox } from '../inbox.ts'
+import { RunStore } from '../store.ts'
+
+export function makeInMemoryDriverLayer(): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeInMemoryDriverLayer(options?: {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: undefined
+}): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeInMemoryDriverLayer(
+  options?: DriverLayerOptions
+): Layer.Layer<Driver, InvalidMaxResumeAttempts, RunStore | Inbox>
+export function makeInMemoryDriverLayer(options?: DriverLayerOptions) {
+  return options === undefined ? Driver.coordinatedLayer() : Driver.coordinatedLayer(options)
+}
+
+export function makeInMemoryHarnessLayer(): Layer.Layer<Driver | RunStore | Inbox>
+export function makeInMemoryHarnessLayer(options?: {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: undefined
+}): Layer.Layer<Driver | RunStore | Inbox>
+export function makeInMemoryHarnessLayer(
+  options?: DriverLayerOptions
+): Layer.Layer<Driver | RunStore | Inbox, InvalidMaxResumeAttempts>
+export function makeInMemoryHarnessLayer(options?: DriverLayerOptions) {
+  const driver =
+    options === undefined ? Driver.coordinatedLayer() : Driver.coordinatedLayer(options)
+
+  return driver.pipe(
+    Layer.provideMerge(RunStore.inMemoryLayer()),
+    Layer.provideMerge(Inbox.layer())
+  )
+}