@orkestrel/workflow 0.0.1

package/dist/src/server/index.cjs

@@ -0,0 +1,129 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/server/NodeScheduler.ts
+/**
+* The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.
+*
+* @remarks
+* - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the
+*   canonical Node "give the host a turn" — it runs AFTER the current operation and
+*   any pending I/O callbacks, so the event loop genuinely regains control before
+*   resuming (unlike a microtask, which drains within the current task). `delay(ms)`
+*   waits on a real `setTimeout`.
+* - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with
+*   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.
+*   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted
+*   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and
+*   a `{ once: true }` abort listener attached, and the two settle paths are mutually
+*   exclusive — the timer path removes the listener before resolving (so a later abort
+*   cannot reach `reject`), and the abort path clears the timer before rejecting (so the
+*   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked
+*   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,
+*   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)
+*   rather than the caller's `signal.reason` — that would break reason fidelity, so the
+*   timer and listener are hand-rolled to match the contract.
+* - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent
+*   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted
+*   for contract compliance and ignored — every yield/delay is uniform.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { NodeScheduler } from '@src/server'
+*
+* const abort = createAbort()
+* const scheduler = new NodeScheduler()
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn
+* }
+* ```
+*/
+var NodeScheduler = class {
+	/**
+	* Yield control back to the event loop via `setImmediate` so pending I/O and timers
+	* can run, then resume; abort rejects with `signal.reason`.
+	*/
+	yield(options) {
+		return this.#immediate(options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive does no validation: it
+	* passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+	* `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+	* throwing.
+	*/
+	delay(ms, options) {
+		return this.#sleep(ms, options?.signal);
+	}
+	#immediate(signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearImmediate(handle);
+				reject(signal?.reason);
+			};
+			const handle = setImmediate(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	#sleep(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a
+* `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)`
+* a real `setTimeout`.
+*
+* @remarks
+* Use it on a server instead of the cross-environment `createScheduler` when a yield
+* should hand the event loop a full turn (after pending I/O) via `setImmediate` rather
+* than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a
+* pending yield/delay rejects with the signal's `reason` (verbatim, with full
+* timer/listener cleanup). `options.priority` is accepted for contract compliance but a
+* no-op — Node has no priority primitive.
+*
+* @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { createNodeScheduler } from '@src/server'
+*
+* const abort = createAbort()
+* const scheduler = createNodeScheduler()
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal: abort.signal })
+* }
+* ```
+*/
+function createNodeScheduler() {
+	return new NodeScheduler();
+}
+//#endregion
+exports.NodeScheduler = NodeScheduler;
+exports.createNodeScheduler = createNodeScheduler;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/server/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["#immediate","#sleep"],"sources":["../../../src/server/NodeScheduler.ts","../../../src/server/factories.ts"],"sourcesContent":["import type { SchedulerInterface, SchedulerOptions } from '@src/core'\n\n/**\n * The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.\n *\n * @remarks\n * - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the\n *   canonical Node \"give the host a turn\" — it runs AFTER the current operation and\n *   any pending I/O callbacks, so the event loop genuinely regains control before\n *   resuming (unlike a microtask, which drains within the current task). `delay(ms)`\n *   waits on a real `setTimeout`.\n * - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with\n *   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.\n *   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted\n *   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and\n *   a `{ once: true }` abort listener attached, and the two settle paths are mutually\n *   exclusive — the timer path removes the listener before resolving (so a later abort\n *   cannot reach `reject`), and the abort path clears the timer before rejecting (so the\n *   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked\n *   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,\n *   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)\n *   rather than the caller's `signal.reason` — that would break reason fidelity, so the\n *   timer and listener are hand-rolled to match the contract.\n * - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent\n *   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted\n *   for contract compliance and ignored — every yield/delay is uniform.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { NodeScheduler } from '@src/server'\n *\n * const abort = createAbort()\n * const scheduler = new NodeScheduler()\n * while (!abort.signal.aborted) {\n * \tdoSomeWork()\n * \tawait scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn\n * }\n * ```\n */\nexport class NodeScheduler implements SchedulerInterface {\n\t/**\n\t * Yield control back to the event loop via `setImmediate` so pending I/O and timers\n\t * can run, then resume; abort rejects with `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#immediate(options?.signal)\n\t}\n\n\t/**\n\t * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * `ms` should be a non-negative finite number. The primitive does no validation: it\n\t * passes `ms` straight to the host `setTimeout`, which clamps a negative value or\n\t * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than\n\t * throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#sleep(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// The `setImmediate` host-turn for `yield`. Resolves after the immediate callback\n\t// fires (after the current operation and pending I/O); rejects with `signal.reason`\n\t// if the signal is already aborted (no immediate armed) or aborts while pending.\n\t// The two settle paths disarm each other: the immediate path removes the abort\n\t// listener before resolving; the abort path clears the immediate before rejecting —\n\t// so it settles exactly once, with no leaked handle and no leaked listener.\n\t#immediate(signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearImmediate(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setImmediate(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t})\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n\n\t// The abort-aware `setTimeout` sleep for `delay`. Same settle-once discipline as\n\t// `#immediate`, with a timer in place of the immediate: an already-aborted signal\n\t// rejects without arming; otherwise the timer path removes the listener before\n\t// resolving and the abort path clears the timer before rejecting with `signal.reason`.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearTimeout(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setTimeout(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t}, ms)\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n}\n","import type { SchedulerInterface } from '@src/core'\nimport { NodeScheduler } from './NodeScheduler.js'\n\n/**\n * Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a\n * `setImmediate` host-turn (the canonical Node \"give the event loop a turn\"), `delay(ms)`\n * a real `setTimeout`.\n *\n * @remarks\n * Use it on a server instead of the cross-environment `createScheduler` when a yield\n * should hand the event loop a full turn (after pending I/O) via `setImmediate` rather\n * than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a\n * pending yield/delay rejects with the signal's `reason` (verbatim, with full\n * timer/listener cleanup). `options.priority` is accepted for contract compliance but a\n * no-op — Node has no priority primitive.\n *\n * @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { createNodeScheduler } from '@src/server'\n *\n * const abort = createAbort()\n * const scheduler = createNodeScheduler()\n * while (!abort.signal.aborted) {\n * \tdoSomeWork()\n * \tawait scheduler.yield({ signal: abort.signal })\n * }\n * ```\n */\nexport function createNodeScheduler(): SchedulerInterface {\n\treturn new NodeScheduler()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAa,gBAAb,MAAyD;;;;;CAKxD,MAAM,SAA2C;EAChD,OAAO,KAAKA,WAAW,SAAS,MAAM;CACvC;;;;;;;;;;;CAYA,MAAM,IAAY,SAA2C;EAC5D,OAAO,KAAKC,OAAO,IAAI,SAAS,MAAM;CACvC;CAUA,WAAW,QAAqC;EAC/C,IAAI,QAAQ,YAAY,MAAM,OAAO,QAAQ,OAAO,OAAO,MAAM;EACjE,OAAO,IAAI,SAAe,SAAS,WAAW;GAC7C,MAAM,gBAAgB;IACrB,eAAe,MAAM;IACrB,OAAO,QAAQ,MAAM;GACtB;GACA,MAAM,SAAS,mBAAmB;IACjC,QAAQ,oBAAoB,SAAS,OAAO;IAC5C,QAAQ;GACT,CAAC;GACD,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D,CAAC;CACF;CAMA,OAAO,IAAY,QAAqC;EACvD,IAAI,QAAQ,YAAY,MAAM,OAAO,QAAQ,OAAO,OAAO,MAAM;EACjE,OAAO,IAAI,SAAe,SAAS,WAAW;GAC7C,MAAM,gBAAgB;IACrB,aAAa,MAAM;IACnB,OAAO,QAAQ,MAAM;GACtB;GACA,MAAM,SAAS,iBAAiB;IAC/B,QAAQ,oBAAoB,SAAS,OAAO;IAC5C,QAAQ;GACT,GAAG,EAAE;GACL,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D,CAAC;CACF;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC1EA,SAAgB,sBAA0C;CACzD,OAAO,IAAI,cAAc;AAC1B"}

package/dist/src/server/index.d.cts

@@ -0,0 +1,93 @@
+import { SchedulerInterface } from '../core/index.js';
+import { SchedulerOptions } from '../core/index.js';
+
+/**
+ * Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a
+ * `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)`
+ * a real `setTimeout`.
+ *
+ * @remarks
+ * Use it on a server instead of the cross-environment `createScheduler` when a yield
+ * should hand the event loop a full turn (after pending I/O) via `setImmediate` rather
+ * than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a
+ * pending yield/delay rejects with the signal's `reason` (verbatim, with full
+ * timer/listener cleanup). `options.priority` is accepted for contract compliance but a
+ * no-op — Node has no priority primitive.
+ *
+ * @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { createNodeScheduler } from '@src/server'
+ *
+ * const abort = createAbort()
+ * const scheduler = createNodeScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doSomeWork()
+ * 	await scheduler.yield({ signal: abort.signal })
+ * }
+ * ```
+ */
+export declare function createNodeScheduler(): SchedulerInterface;
+
+/**
+ * The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.
+ *
+ * @remarks
+ * - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the
+ *   canonical Node "give the host a turn" — it runs AFTER the current operation and
+ *   any pending I/O callbacks, so the event loop genuinely regains control before
+ *   resuming (unlike a microtask, which drains within the current task). `delay(ms)`
+ *   waits on a real `setTimeout`.
+ * - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with
+ *   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.
+ *   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted
+ *   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and
+ *   a `{ once: true }` abort listener attached, and the two settle paths are mutually
+ *   exclusive — the timer path removes the listener before resolving (so a later abort
+ *   cannot reach `reject`), and the abort path clears the timer before rejecting (so the
+ *   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked
+ *   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,
+ *   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)
+ *   rather than the caller's `signal.reason` — that would break reason fidelity, so the
+ *   timer and listener are hand-rolled to match the contract.
+ * - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent
+ *   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted
+ *   for contract compliance and ignored — every yield/delay is uniform.
+ * - **Event-free.** A pure functional primitive — no Emitter, no events.
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { NodeScheduler } from '@src/server'
+ *
+ * const abort = createAbort()
+ * const scheduler = new NodeScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doSomeWork()
+ * 	await scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn
+ * }
+ * ```
+ */
+export declare class NodeScheduler implements SchedulerInterface {
+    #private;
+    /**
+     * Yield control back to the event loop via `setImmediate` so pending I/O and timers
+     * can run, then resume; abort rejects with `signal.reason`.
+     */
+    yield(options?: SchedulerOptions): Promise<void>;
+    /**
+     * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+     * `signal.reason`.
+     *
+     * @remarks
+     * `ms` should be a non-negative finite number. The primitive does no validation: it
+     * passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+     * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+     * throwing.
+     */
+    delay(ms: number, options?: SchedulerOptions): Promise<void>;
+}
+
+export { }

package/dist/src/server/index.d.ts

@@ -0,0 +1,93 @@
+import { SchedulerInterface } from '../core/index.js';
+import { SchedulerOptions } from '../core/index.js';
+
+/**
+ * Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a
+ * `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)`
+ * a real `setTimeout`.
+ *
+ * @remarks
+ * Use it on a server instead of the cross-environment `createScheduler` when a yield
+ * should hand the event loop a full turn (after pending I/O) via `setImmediate` rather
+ * than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a
+ * pending yield/delay rejects with the signal's `reason` (verbatim, with full
+ * timer/listener cleanup). `options.priority` is accepted for contract compliance but a
+ * no-op — Node has no priority primitive.
+ *
+ * @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { createNodeScheduler } from '@src/server'
+ *
+ * const abort = createAbort()
+ * const scheduler = createNodeScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doSomeWork()
+ * 	await scheduler.yield({ signal: abort.signal })
+ * }
+ * ```
+ */
+export declare function createNodeScheduler(): SchedulerInterface;
+
+/**
+ * The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.
+ *
+ * @remarks
+ * - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the
+ *   canonical Node "give the host a turn" — it runs AFTER the current operation and
+ *   any pending I/O callbacks, so the event loop genuinely regains control before
+ *   resuming (unlike a microtask, which drains within the current task). `delay(ms)`
+ *   waits on a real `setTimeout`.
+ * - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with
+ *   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.
+ *   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted
+ *   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and
+ *   a `{ once: true }` abort listener attached, and the two settle paths are mutually
+ *   exclusive — the timer path removes the listener before resolving (so a later abort
+ *   cannot reach `reject`), and the abort path clears the timer before rejecting (so the
+ *   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked
+ *   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,
+ *   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)
+ *   rather than the caller's `signal.reason` — that would break reason fidelity, so the
+ *   timer and listener are hand-rolled to match the contract.
+ * - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent
+ *   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted
+ *   for contract compliance and ignored — every yield/delay is uniform.
+ * - **Event-free.** A pure functional primitive — no Emitter, no events.
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { NodeScheduler } from '@src/server'
+ *
+ * const abort = createAbort()
+ * const scheduler = new NodeScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doSomeWork()
+ * 	await scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn
+ * }
+ * ```
+ */
+export declare class NodeScheduler implements SchedulerInterface {
+    #private;
+    /**
+     * Yield control back to the event loop via `setImmediate` so pending I/O and timers
+     * can run, then resume; abort rejects with `signal.reason`.
+     */
+    yield(options?: SchedulerOptions): Promise<void>;
+    /**
+     * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+     * `signal.reason`.
+     *
+     * @remarks
+     * `ms` should be a non-negative finite number. The primitive does no validation: it
+     * passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+     * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+     * throwing.
+     */
+    delay(ms: number, options?: SchedulerOptions): Promise<void>;
+}
+
+export { }

package/dist/src/server/index.js

@@ -0,0 +1,127 @@
+//#region src/server/NodeScheduler.ts
+/**
+* The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.
+*
+* @remarks
+* - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the
+*   canonical Node "give the host a turn" — it runs AFTER the current operation and
+*   any pending I/O callbacks, so the event loop genuinely regains control before
+*   resuming (unlike a microtask, which drains within the current task). `delay(ms)`
+*   waits on a real `setTimeout`.
+* - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with
+*   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.
+*   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted
+*   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and
+*   a `{ once: true }` abort listener attached, and the two settle paths are mutually
+*   exclusive — the timer path removes the listener before resolving (so a later abort
+*   cannot reach `reject`), and the abort path clears the timer before rejecting (so the
+*   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked
+*   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,
+*   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)
+*   rather than the caller's `signal.reason` — that would break reason fidelity, so the
+*   timer and listener are hand-rolled to match the contract.
+* - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent
+*   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted
+*   for contract compliance and ignored — every yield/delay is uniform.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { NodeScheduler } from '@src/server'
+*
+* const abort = createAbort()
+* const scheduler = new NodeScheduler()
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn
+* }
+* ```
+*/
+var NodeScheduler = class {
+	/**
+	* Yield control back to the event loop via `setImmediate` so pending I/O and timers
+	* can run, then resume; abort rejects with `signal.reason`.
+	*/
+	yield(options) {
+		return this.#immediate(options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive does no validation: it
+	* passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+	* `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+	* throwing.
+	*/
+	delay(ms, options) {
+		return this.#sleep(ms, options?.signal);
+	}
+	#immediate(signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearImmediate(handle);
+				reject(signal?.reason);
+			};
+			const handle = setImmediate(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	#sleep(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a
+* `setImmediate` host-turn (the canonical Node "give the event loop a turn"), `delay(ms)`
+* a real `setTimeout`.
+*
+* @remarks
+* Use it on a server instead of the cross-environment `createScheduler` when a yield
+* should hand the event loop a full turn (after pending I/O) via `setImmediate` rather
+* than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a
+* pending yield/delay rejects with the signal's `reason` (verbatim, with full
+* timer/listener cleanup). `options.priority` is accepted for contract compliance but a
+* no-op — Node has no priority primitive.
+*
+* @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { createNodeScheduler } from '@src/server'
+*
+* const abort = createAbort()
+* const scheduler = createNodeScheduler()
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal: abort.signal })
+* }
+* ```
+*/
+function createNodeScheduler() {
+	return new NodeScheduler();
+}
+//#endregion
+export { NodeScheduler, createNodeScheduler };
+
+//# sourceMappingURL=index.js.map

package/dist/src/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#immediate","#sleep"],"sources":["../../../src/server/NodeScheduler.ts","../../../src/server/factories.ts"],"sourcesContent":["import type { SchedulerInterface, SchedulerOptions } from '@src/core'\n\n/**\n * The Node {@link SchedulerInterface} — the server-native cooperative-yield backend.\n *\n * @remarks\n * - **`yield` is a `setImmediate` host-turn.** `yield()` waits on `setImmediate`, the\n *   canonical Node \"give the host a turn\" — it runs AFTER the current operation and\n *   any pending I/O callbacks, so the event loop genuinely regains control before\n *   resuming (unlike a microtask, which drains within the current task). `delay(ms)`\n *   waits on a real `setTimeout`.\n * - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with\n *   `signal.reason` exactly — the value the caller passed, never wrapped or replaced.\n *   The discipline mirrors the cross-environment default's `#sleep`: an already-aborted\n *   signal rejects immediately WITHOUT arming a timer; otherwise the timer is armed and\n *   a `{ once: true }` abort listener attached, and the two settle paths are mutually\n *   exclusive — the timer path removes the listener before resolving (so a later abort\n *   cannot reach `reject`), and the abort path clears the timer before rejecting (so the\n *   macrotask cannot reach `resolve`). The promise settles exactly once, with no leaked\n *   timer and no leaked listener. It deliberately does NOT use `node:timers/promises`,\n *   whose `{ signal }` option rejects with a Node `AbortError` (`code: 'ABORT_ERR'`)\n *   rather than the caller's `signal.reason` — that would break reason fidelity, so the\n *   timer and listener are hand-rolled to match the contract.\n * - **Priority is accepted but a no-op.** Node has no priority primitive (no equivalent\n *   of the browser's `scheduler.postTask` priorities), so `options.priority` is accepted\n *   for contract compliance and ignored — every yield/delay is uniform.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { NodeScheduler } from '@src/server'\n *\n * const abort = createAbort()\n * const scheduler = new NodeScheduler()\n * while (!abort.signal.aborted) {\n * \tdoSomeWork()\n * \tawait scheduler.yield({ signal: abort.signal }) // a setImmediate host-turn\n * }\n * ```\n */\nexport class NodeScheduler implements SchedulerInterface {\n\t/**\n\t * Yield control back to the event loop via `setImmediate` so pending I/O and timers\n\t * can run, then resume; abort rejects with `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#immediate(options?.signal)\n\t}\n\n\t/**\n\t * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * `ms` should be a non-negative finite number. The primitive does no validation: it\n\t * passes `ms` straight to the host `setTimeout`, which clamps a negative value or\n\t * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than\n\t * throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#sleep(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// The `setImmediate` host-turn for `yield`. Resolves after the immediate callback\n\t// fires (after the current operation and pending I/O); rejects with `signal.reason`\n\t// if the signal is already aborted (no immediate armed) or aborts while pending.\n\t// The two settle paths disarm each other: the immediate path removes the abort\n\t// listener before resolving; the abort path clears the immediate before rejecting —\n\t// so it settles exactly once, with no leaked handle and no leaked listener.\n\t#immediate(signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearImmediate(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setImmediate(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t})\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n\n\t// The abort-aware `setTimeout` sleep for `delay`. Same settle-once discipline as\n\t// `#immediate`, with a timer in place of the immediate: an already-aborted signal\n\t// rejects without arming; otherwise the timer path removes the listener before\n\t// resolving and the abort path clears the timer before rejecting with `signal.reason`.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearTimeout(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setTimeout(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t}, ms)\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n}\n","import type { SchedulerInterface } from '@src/core'\nimport { NodeScheduler } from './NodeScheduler.js'\n\n/**\n * Create the Node-native cooperative-yield {@link SchedulerInterface} — `yield()` is a\n * `setImmediate` host-turn (the canonical Node \"give the event loop a turn\"), `delay(ms)`\n * a real `setTimeout`.\n *\n * @remarks\n * Use it on a server instead of the cross-environment `createScheduler` when a yield\n * should hand the event loop a full turn (after pending I/O) via `setImmediate` rather\n * than a zero-delay timer. Both methods are abort-aware: pass `options.signal` and a\n * pending yield/delay rejects with the signal's `reason` (verbatim, with full\n * timer/listener cleanup). `options.priority` is accepted for contract compliance but a\n * no-op — Node has no priority primitive.\n *\n * @returns A {@link SchedulerInterface} backed by Node's `setImmediate` / `setTimeout`\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { createNodeScheduler } from '@src/server'\n *\n * const abort = createAbort()\n * const scheduler = createNodeScheduler()\n * while (!abort.signal.aborted) {\n * \tdoSomeWork()\n * \tawait scheduler.yield({ signal: abort.signal })\n * }\n * ```\n */\nexport function createNodeScheduler(): SchedulerInterface {\n\treturn new NodeScheduler()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAa,gBAAb,MAAyD;;;;;CAKxD,MAAM,SAA2C;EAChD,OAAO,KAAKA,WAAW,SAAS,MAAM;CACvC;;;;;;;;;;;CAYA,MAAM,IAAY,SAA2C;EAC5D,OAAO,KAAKC,OAAO,IAAI,SAAS,MAAM;CACvC;CAUA,WAAW,QAAqC;EAC/C,IAAI,QAAQ,YAAY,MAAM,OAAO,QAAQ,OAAO,OAAO,MAAM;EACjE,OAAO,IAAI,SAAe,SAAS,WAAW;GAC7C,MAAM,gBAAgB;IACrB,eAAe,MAAM;IACrB,OAAO,QAAQ,MAAM;GACtB;GACA,MAAM,SAAS,mBAAmB;IACjC,QAAQ,oBAAoB,SAAS,OAAO;IAC5C,QAAQ;GACT,CAAC;GACD,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D,CAAC;CACF;CAMA,OAAO,IAAY,QAAqC;EACvD,IAAI,QAAQ,YAAY,MAAM,OAAO,QAAQ,OAAO,OAAO,MAAM;EACjE,OAAO,IAAI,SAAe,SAAS,WAAW;GAC7C,MAAM,gBAAgB;IACrB,aAAa,MAAM;IACnB,OAAO,QAAQ,MAAM;GACtB;GACA,MAAM,SAAS,iBAAiB;IAC/B,QAAQ,oBAAoB,SAAS,OAAO;IAC5C,QAAQ;GACT,GAAG,EAAE;GACL,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D,CAAC;CACF;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC1EA,SAAgB,sBAA0C;CACzD,OAAO,IAAI,cAAc;AAC1B"}

package/package.json

@@ -0,0 +1,111 @@
+{
+	"name": "@orkestrel/workflow",
+	"version": "0.0.1",
+	"description": "A typed workflow engine for the @orkestrel line — a serializable Workflow → Phase → Task tree run by a composed runner on a cooperative scheduler. Part of the @orkestrel line.",
+	"keywords": [
+		"orchestration",
+		"runner",
+		"scheduler",
+		"task",
+		"typescript",
+		"workflow"
+	],
+	"homepage": "https://github.com/orkestrel/workflow#readme",
+	"bugs": "https://github.com/orkestrel/workflow/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/orkestrel/workflow.git"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/src/core/index.cjs",
+	"module": "./dist/src/core/index.js",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/src/core/index.d.ts",
+				"default": "./dist/src/core/index.js"
+			},
+			"require": {
+				"types": "./dist/src/core/index.d.cts",
+				"default": "./dist/src/core/index.cjs"
+			}
+		},
+		"./browser": {
+			"import": {
+				"types": "./dist/src/browser/index.d.ts",
+				"default": "./dist/src/browser/index.js"
+			}
+		},
+		"./server": {
+			"import": {
+				"types": "./dist/src/server/index.d.ts",
+				"default": "./dist/src/server/index.js"
+			},
+			"require": {
+				"types": "./dist/src/server/index.d.cts",
+				"default": "./dist/src/server/index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
+		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"check": "tsc --noEmit --project tsconfig.json",
+		"check:src": "npm run check:src:core && npm run check:src:browser && npm run check:src:server",
+		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
+		"check:src:browser": "tsc --noEmit -p configs/src/tsconfig.browser.json",
+		"check:src:server": "tsc --noEmit -p configs/src/tsconfig.server.json",
+		"format": "oxfmt --config .oxfmtrc.json --write .",
+		"format:check": "oxfmt --config .oxfmtrc.json --check .",
+		"lint:check": "oxlint --config .oxlintrc.json .",
+		"test": "npm run test:src && npm run test:guides",
+		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core --project src:browser --project src:server",
+		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:src:browser": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:browser",
+		"test:src:server": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
+		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
+		"build": "npm run clean && npm run build:src",
+		"build:src": "npm run build:src:core && npm run build:src:browser && npm run build:src:server",
+		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"build:src:browser": "vite build --config configs/src/vite.browser.config.ts",
+		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check:src && npm run build && npm test"
+	},
+	"dependencies": {
+		"@orkestrel/abort": "^0.0.1",
+		"@orkestrel/agent": "^0.0.1",
+		"@orkestrel/budget": "^0.0.1",
+		"@orkestrel/contract": "^0.0.1",
+		"@orkestrel/database": "^0.0.2",
+		"@orkestrel/emitter": "^0.0.1",
+		"@orkestrel/queue": "^0.0.1",
+		"@orkestrel/timeout": "^0.0.1"
+	},
+	"devDependencies": {
+		"@microsoft/api-extractor": "^7.58.9",
+		"@orkestrel/guide": "^0.0.1",
+		"@types/node": "^26.1.1",
+		"@vitest/browser-playwright": "^4.1.10",
+		"oxfmt": "^0.58.0",
+		"oxlint": "^1.73.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.4",
+		"vite-plugin-dts": "^5.0.3",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=24"
+	}
+}