From af88aacf3698016b0f9c652d5792ee499bfe1fd5 Mon Sep 17 00:00:00 2001
From: Devin Ivy <devinivy@gmail.com>
Date: Fri, 24 Apr 2026 16:16:21 -0400
Subject: [PATCH] feat(serve): scaffold subpath + public types

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 package.json       |  9 ++++++++-
 src/serve/index.ts |  1 +
 src/serve/types.ts | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 src/serve/index.ts
 create mode 100644 src/serve/types.ts

diff --git a/package.json b/package.json
index 68bae5a..10cba5e 100644
--- a/package.json
+++ b/package.json
@@ -8,12 +8,19 @@
   "homepage": "https://tangled.org/divy.zone/moroutine",
   "license": "MIT",
   "type": "module",
-  "exports": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./serve": "./src/serve/index.ts"
+  },
   "publishConfig": {
     "exports": {
       ".": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
+      },
+      "./serve": {
+        "types": "./dist/serve/index.d.ts",
+        "default": "./dist/serve/index.js"
       }
     }
   },
diff --git a/src/serve/index.ts b/src/serve/index.ts
new file mode 100644
index 0000000..8489f72
--- /dev/null
+++ b/src/serve/index.ts
@@ -0,0 +1 @@
+export type { ListenArgs, ListenOptions, Balance, ServerThreads, ServerThreadsOptions } from './types.ts';
diff --git a/src/serve/types.ts b/src/serve/types.ts
new file mode 100644
index 0000000..680cfda
--- /dev/null
+++ b/src/serve/types.ts
@@ -0,0 +1,41 @@
+import type { Channel } from '../channel.ts';
+import type { Tuple } from '../shared/tuple.ts';
+import type { Int32Atomic } from '../shared/int32-atomic.ts';
+import type { WorkerHandle } from '../runner.ts';
+
+/** Worker-side options, configured on `serverThreads` and shipped via `ListenArgs`. */
+export interface ListenOptions {
+  /** Per-worker drain budget after the channel ends, in ms. Default 30_000. */
+  drainTimeout?: number;
+}
+
+/**
+ * Opaque tuple passed from `serverThreads` to each worker's moroutine.
+ * The shape may evolve; users only ever spread it into `listen()`.
+ */
+export type ListenArgs = readonly [
+  channel: Channel<number>,
+  counters: Tuple<Int32Atomic[]>,
+  slot: number,
+  opts: Required<ListenOptions>,
+];
+
+/** Connection-routing strategy. Picks a worker index given a counter snapshot. */
+export interface Balance {
+  pick(counters: readonly number[]): number;
+}
+
+export interface ServerThreadsOptions {
+  /** Routing strategy. Default: `leastConns()`. */
+  balance?: Balance;
+  /** Options forwarded to each worker's `listen()` call. */
+  listen?: ListenOptions;
+  /** Per-worker fd-channel buffer size. Default 64. */
+  highWaterMark?: number;
+}
+
+/**
+ * Disposable bundle pairing each `WorkerHandle` with its opaque `ListenArgs` tuple.
+ * Iterable / indexable / `.map`-able.
+ */
+export interface ServerThreads extends Disposable, ReadonlyArray<readonly [WorkerHandle, ListenArgs]> {}
-- 
2.51.2