@orkestrel/workflow 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @orkestrel/workflow
+
+A typed workflow engine for the `@orkestrel` line — a serializable
+`Workflow → Phase → Task` tree that a UI or an LLM authors as pure JSON, and
+a thin `WorkflowRunner` executes by COMPOSING the shipped substrate (a
+per-phase `Runner`, `Abort`, `Timeout`, `Budget`, and a cooperative
+cross-environment `Scheduler`) rather than re-implementing its own
+concurrency / retry / abort machinery.
+
+## Install
+
+```sh
+npm install @orkestrel/workflow
+```
+
+## Requirements
+
+- Core is cross-environment ESM; `./browser` adds browser-native cooperative
+  scheduler backends (`requestAnimationFrame` / `requestIdleCallback` /
+  Prioritized Task Scheduling), `./server` adds the Node-native
+  `setImmediate` scheduler backend
+
+## Status
+
+Pre-release (`0.0.1`): the definition contract, the live entity tree, the
+thin runner (with the `function` / `tool` / `agent` task forms and the
+depth/cycle-bounded agent-native recursion), the durable `WorkflowStore`
+(in-memory + driver-pluggable), and the cooperative `Scheduler` (the
+cross-environment default plus the browser and Node environment backends)
+are all implemented and tested, but the public API is still unstable and
+may change without notice. See [guides/src/workflow.md](./guides/src/workflow.md)
+for the full documented surface.
+
+## Package
+
+Published as three environment-scoped entry points per the `exports` field
+in `package.json`: `.` (the shared, environment-agnostic core — the
+definition/entity/runner surface plus the cross-environment `Scheduler`
+default), `./browser` (adds the browser-native scheduler backends), and
+`./server` (adds the Node-native scheduler backend). Core ships dual
+ESM+CJS builds; `./browser` is ESM-only.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,279 @@
+import { SchedulerInterface } from '../core/index.js';
+import { SchedulerOptions } from '../core/index.js';
+import { SchedulerPriority } from '../core/index.js';
+
+/**
+ * The browser {@link SchedulerInterface} — the browser-native cooperative-yield backend
+ * built on the Prioritized Task Scheduling API (`scheduler.postTask`), falling back to a
+ * zero-delay macrotask where it is absent.
+ *
+ * @remarks
+ * - **`yield` prefers `scheduler.postTask`, honouring priority.** When `globalThis`
+ *   exposes a `scheduler` with a `postTask` method, `yield()` posts a task at the mapped
+ *   priority (`user` → `'user-blocking'`, `normal` → `'user-visible'`, `background` →
+ *   `'background'`), so the host genuinely regains control and the urgency hint is
+ *   honoured. The capability is feature-detected through guards (`isRecord` / `isFunction`),
+ *   never an `as` (AGENTS §14). Where the API is absent (Firefox today, older engines),
+ *   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, just
+ *   without priority. `delay(ms)` is always 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 scheduling; otherwise the host-turn is scheduled and a
+ *   `{ once: true }` abort listener attached, and the two settle paths are mutually
+ *   exclusive — the turn path removes the listener before resolving, and the abort path
+ *   cancels the scheduled turn before rejecting. The promise settles exactly once, with no
+ *   leaked task/timer and no leaked listener. The caller's `signal` is NOT handed to
+ *   `postTask` (whose own abort would reject with a platform `AbortError`, not the
+ *   caller's `reason`); instead an internal controller cancels the posted task while this
+ *   scheduler rejects with the verbatim `signal.reason`.
+ * - **Event-free.** A pure functional primitive — no Emitter, no events.
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { BrowserScheduler } from '@src/browser'
+ *
+ * const abort = createAbort()
+ * const scheduler = new BrowserScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doSomeWork()
+ * 	await scheduler.yield({ priority: 'background', signal: abort.signal })
+ * }
+ * ```
+ */
+export declare class BrowserScheduler implements SchedulerInterface {
+    #private;
+    /**
+     * Yield control to the host via `scheduler.postTask` at the given priority (or a
+     * `setTimeout(0)` macrotask where the API is absent), 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>;
+}
+
+/**
+ * Create the browser-native cooperative-yield {@link SchedulerInterface} — `yield()` uses
+ * the Prioritized Task Scheduling API (`scheduler.postTask`) at the requested priority
+ * when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real
+ * `setTimeout`.
+ *
+ * @remarks
+ * The default browser scheduler: it honours `options.priority` (`user` /
+ * `normal` / `background`) when `scheduler.postTask` is available and degrades to a plain
+ * macrotask elsewhere. Both methods are abort-aware: pass `options.signal` and a pending
+ * yield/delay rejects with the signal's `reason` verbatim, with full task/timer/listener
+ * cleanup. Prefer {@link createFrameScheduler} for paint-aligned work or
+ * {@link createIdleScheduler} for idle-time background work.
+ *
+ * @returns A {@link SchedulerInterface} backed by `scheduler.postTask` (or a macrotask)
+ *
+ * @example
+ * ```ts
+ * import { createBrowserScheduler } from '@src/browser'
+ *
+ * const scheduler = createBrowserScheduler()
+ * await scheduler.yield({ priority: 'background' })
+ * ```
+ */
+export declare function createBrowserScheduler(): SchedulerInterface;
+
+/**
+ * Create the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes
+ * just before the next paint via `requestAnimationFrame`; `delay(ms)` is a real
+ * `setTimeout`.
+ *
+ * @remarks
+ * Use it for work that should batch per render frame (animation, incremental DOM updates)
+ * and naturally pause while the tab is hidden. `yield` is abort-aware: pass `options.signal`
+ * and a pending yield rejects with the signal's `reason` verbatim, cancelling the pending
+ * frame request. `options.priority` is accepted but a no-op — a frame callback has no
+ * priority dimension.
+ *
+ * @returns A {@link SchedulerInterface} backed by `requestAnimationFrame`
+ *
+ * @example
+ * ```ts
+ * import { createFrameScheduler } from '@src/browser'
+ *
+ * const scheduler = createFrameScheduler()
+ * await scheduler.yield() // resumes before the next paint
+ * ```
+ */
+export declare function createFrameScheduler(): SchedulerInterface;
+
+/**
+ * Create the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when
+ * the host is idle via `requestIdleCallback` when present, falling back to a `setTimeout(0)`
+ * macrotask; `delay(ms)` is a real `setTimeout`.
+ *
+ * @remarks
+ * Use it for low-priority background work that must not contend with rendering or input.
+ * Where `requestIdleCallback` is absent (Safari today) it degrades to a plain macrotask.
+ * `yield` is abort-aware: pass `options.signal` and a pending yield rejects with the
+ * signal's `reason` verbatim, cancelling the pending idle callback. `options.priority` is
+ * accepted but a no-op — idle scheduling has no priority dimension.
+ *
+ * @returns A {@link SchedulerInterface} backed by `requestIdleCallback` (or a macrotask)
+ *
+ * @example
+ * ```ts
+ * import { createIdleScheduler } from '@src/browser'
+ *
+ * const scheduler = createIdleScheduler()
+ * await scheduler.yield() // resumes when the host is idle
+ * ```
+ */
+export declare function createIdleScheduler(): SchedulerInterface;
+
+/**
+ * The frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend
+ * whose `yield` resumes just before the next paint via `requestAnimationFrame`.
+ *
+ * @remarks
+ * - **`yield` resumes before the next paint.** `yield()` waits on `requestAnimationFrame`,
+ *   so the resumption is aligned to the browser's render loop — ideal for work that
+ *   should batch per frame (animation, incremental DOM updates) and pause while the tab
+ *   is hidden (the host throttles rAF). `delay(ms)` is a real `setTimeout`, unaligned to
+ *   frames. `options.priority` is accepted for contract compliance but a no-op — a frame
+ *   callback has no priority dimension.
+ * - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with
+ *   `signal.reason` exactly. The discipline mirrors the cross-environment default's
+ *   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling a frame;
+ *   otherwise the frame is requested and a `{ once: true }` abort listener attached, and
+ *   the two settle paths are mutually exclusive — the frame path removes the listener
+ *   before resolving, and the abort path `cancelAnimationFrame`s the pending handle before
+ *   rejecting. The promise settles exactly once, with no leaked frame request and no
+ *   leaked listener.
+ * - **Event-free.** A pure functional primitive — no Emitter, no events.
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { FrameScheduler } from '@src/browser'
+ *
+ * const abort = createAbort()
+ * const scheduler = new FrameScheduler()
+ * while (!abort.signal.aborted) {
+ * 	renderOneFrameOfWork()
+ * 	await scheduler.yield({ signal: abort.signal }) // resume before the next paint
+ * }
+ * ```
+ */
+export declare class FrameScheduler implements SchedulerInterface {
+    #private;
+    /**
+     * Yield control to the host until just before the next paint via
+     * `requestAnimationFrame`, 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>;
+}
+
+/**
+ * The narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off
+ * `globalThis`.
+ *
+ * @remarks
+ * A `request` taking a callback and returning a numeric handle, and a `cancel` taking that
+ * handle. {@link IdleScheduler} feature-detects the pair through a guard (`isFunction`,
+ * never an `as` — AGENTS §14) and resolves to `undefined` when the API is absent (Safari
+ * today), so `yield` falls back to a macrotask.
+ */
+export declare interface IdleAPI {
+    readonly request: (callback: () => void) => number;
+    readonly cancel: (handle: number) => void;
+}
+
+/**
+ * The idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose
+ * `yield` resumes when the host is idle via `requestIdleCallback`, falling back to a
+ * zero-delay macrotask where it is absent.
+ *
+ * @remarks
+ * - **`yield` resumes during idle time.** When `globalThis` exposes `requestIdleCallback`,
+ *   `yield()` waits on it, so the resumption happens when the browser has spare time after
+ *   rendering and input — ideal for low-priority background work that must not contend with
+ *   the user. The capability is feature-detected through a guard (`isFunction`), never an
+ *   `as` (AGENTS §14). Where the API is absent (Safari today), it **falls back** to a
+ *   `setTimeout(0)` macrotask — still a real host-turn, just not idle-gated. `delay(ms)` is
+ *   always a real `setTimeout`. `options.priority` is accepted for contract compliance but a
+ *   no-op — idle scheduling has no priority dimension.
+ * - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with
+ *   `signal.reason` exactly. The discipline mirrors the cross-environment default's
+ *   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling; otherwise
+ *   the idle callback (or fallback timer) is requested and a `{ once: true }` abort listener
+ *   attached, and the two settle paths are mutually exclusive — the resume path removes the
+ *   listener before resolving, and the abort path `cancelIdleCallback`s (or `clearTimeout`s)
+ *   the pending handle before rejecting. The promise settles exactly once, with no leaked
+ *   callback/timer and no leaked listener.
+ * - **Event-free.** A pure functional primitive — no Emitter, no events.
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '../core/index.js'
+ * import { IdleScheduler } from '@src/browser'
+ *
+ * const abort = createAbort()
+ * const scheduler = new IdleScheduler()
+ * while (!abort.signal.aborted) {
+ * 	doLowPriorityWork()
+ * 	await scheduler.yield({ signal: abort.signal }) // resume when the host is idle
+ * }
+ * ```
+ */
+export declare class IdleScheduler implements SchedulerInterface {
+    #private;
+    /**
+     * Yield control to the host until it is idle via `requestIdleCallback` (or a
+     * `setTimeout(0)` macrotask where the API is absent), 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>;
+}
+
+/**
+ * The browser-native `postTask` priority for each portable {@link SchedulerPriority} — the
+ * Prioritized Task Scheduling API's three levels.
+ *
+ * @remarks
+ * A `user` hint maps to the most urgent `'user-blocking'`, `normal` to the default
+ * `'user-visible'`, and `background` to `'background'`. {@link BrowserScheduler} reads this
+ * map to translate the caller's portable priority into the value passed to
+ * `scheduler.postTask`, so the urgency hint is honoured by the host.
+ */
+export declare const POST_TASK_PRIORITY: Readonly<Record<SchedulerPriority, string>>;
+
+export { }