@orkestrel/workflow 0.0.10 → 0.0.11

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

@@ -152,7 +152,7 @@ export declare function cloneWorkflowSnapshot(input: unknown, id?: string): Work
  * @param phases - The per-phase result lists, in phase order
  * @returns One flattened {@link TaskResult} list, in positional order
  */
-export declare function collectResults(phases: readonly (readonly TaskResult[])[]): readonly TaskResult[];
+export declare function collectResults(phases: ReadonlyArray<readonly TaskResult[]>): readonly TaskResult[];
 
 /**
  * The per-unit handle a runner handler receives — wraps the unit's identity,
@@ -865,7 +865,7 @@ export declare function hasWorkflowHandlers(workflow: WorkflowSnapshot, function
  * insertEntry([['a', 1], ['b', 2]], 1, 'c', 3) // [['a', 1], ['c', 3], ['b', 2]]
  * ```
  */
-export declare function insertEntry<T>(entries: readonly (readonly [string, T])[], index: number, key: string, value: T): readonly (readonly [string, T])[];
+export declare function insertEntry<T>(entries: ReadonlyArray<readonly [string, T]>, index: number, key: string, value: T): ReadonlyArray<readonly [string, T]>;
 
 /** Test the workflow lifecycle vocabulary. */
 export declare function isLifecycleStatus(value: unknown): value is LifecycleStatus;
@@ -943,8 +943,9 @@ export declare function isWorkflowSnapshot(value: unknown): value is WorkflowSna
  * name + doc while the vocabulary lives in one place (AGENTS §4.4 "one concept = one
  * word"). It also types the single runtime terminal check
  * {@link import('./helpers.js').isTerminalStatus} — every tier's value is a
- * `LifecycleStatus`, so the one predicate accepts them all. The tiers stay distinct
- * types (a phase status is not a task status) even though they currently share a body.
+ * `LifecycleStatus`, so the one predicate accepts them all. The three tiers are direct
+ * aliases, not branded types, so TypeScript accepts any one of them wherever another is
+ * expected. Each name documents which tier a value came from; it does not enforce it.
  */
 export declare type LifecycleStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'stopped';
 
@@ -1024,7 +1025,7 @@ export declare class MemoryWorkflowStore implements WorkflowStoreInterface {
  * moveEntry([['a', 1], ['b', 2], ['c', 3]], 'a', 2) // [['b', 2], ['c', 3], ['a', 1]]
  * ```
  */
-export declare function moveEntry<T>(entries: readonly (readonly [string, T])[], key: string, index: number): readonly (readonly [string, T])[];
+export declare function moveEntry<T>(entries: ReadonlyArray<readonly [string, T]>, key: string, index: number): ReadonlyArray<readonly [string, T]>;
 
 /**
  * Park until `signal` aborts — a promise-parked wait (AGENTS §21), never a timer or
@@ -2104,6 +2105,16 @@ export declare interface RunnerUnit<TInput> {
  * Schedule one cancellable host operation behind an owned settlement signal.
  *
  * @remarks
+ * A defined `signal` that is not a native `AbortSignal` is refused before anything is armed, as a
+ * rejected promise carrying a {@link import('./errors.js').WorkflowError} with the `SCHEDULE` code.
+ * Rejecting rather than throwing keeps every caller on one settlement path, so a backend never has
+ * to guard the call itself.
+ *
+ * The guard is necessary but not sufficient, so linking stays contained. A `Proxy` over a native
+ * signal passes the guard and can still make linking throw from a trap, and that escape would be
+ * synchronous — the one shape every caller here is built not to expect. Containment turns it into
+ * the same `SCHEDULE` rejection, so setup has exactly one failure shape however hostile the input.
+ *
  * The completion and failure paths each own an {@link AbortController}; their native composite is
  * linked to the optional caller signal before `start` can arm host work. Scheduler backends attach
  * only to that safe composite, so caller mutation of `addEventListener` or `removeEventListener`
@@ -2115,7 +2126,8 @@ export declare interface RunnerUnit<TInput> {
  *
  * @param start - Arm host work and return its cancellation closure
  * @param signal - Optional caller cancellation signal
- * @returns A promise settled exactly once by completion, host failure, or caller abort
+ * @returns A promise settled exactly once by an invalid-signal refusal, completion, host failure,
+ *   or caller abort
  */
 export declare function scheduleHost(start: (complete: () => void, failure: (error: unknown) => void) => () => void, signal?: AbortSignal): Promise<void>;
 
@@ -3138,9 +3150,11 @@ export declare interface WorkflowDefinition {
  *
  * @remarks
  * Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
- * offending node id / status. Raised for an illegal lifecycle transition
+ * offending node id / status / parameter. Raised for an illegal lifecycle transition
  * (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
- * boundary (`RESTORE`), or a refused structural/activity edit (`MUTATION`).
+ * boundary (`RESTORE`), a refused structural/activity edit (`MUTATION`), or a host
+ * schedule refused before arming because the caller's `signal` is not a native
+ * `AbortSignal` (`SCHEDULE`, delivered as a rejected promise).
  */
 export declare class WorkflowError extends Error {
     readonly code: WorkflowErrorCode;
@@ -3170,8 +3184,13 @@ export declare class WorkflowError extends Error {
  *   {@link TaskManagerInterface.append} / {@link PhaseManagerInterface.append} duplicate-id
  *   guard (both genuine programmer-error paths, AGENTS §12). The error `context` names
  *   the offending id / index / status.
+ * - `SCHEDULE` — {@link import('./helpers.js').scheduleHost} refused to arm host work
+ *   because the caller passed a `signal` that is not a native `AbortSignal`. The refusal
+ *   is a REJECTED promise, never a synchronous throw, so every scheduler backend settles
+ *   the same way whatever the caller passed. The error `context` names the offending
+ *   parameter (`signal`) and the `typeof` the caller supplied.
  */
-export declare type WorkflowErrorCode = 'TRANSITION' | 'RESTORE' | 'MUTATION';
+export declare type WorkflowErrorCode = 'TRANSITION' | 'RESTORE' | 'MUTATION' | 'SCHEDULE';
 
 /**
  * The push observation surface (AGENTS §13) of the workflow entity (W-b) — the

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

@@ -152,7 +152,7 @@ export declare function cloneWorkflowSnapshot(input: unknown, id?: string): Work
  * @param phases - The per-phase result lists, in phase order
  * @returns One flattened {@link TaskResult} list, in positional order
  */
-export declare function collectResults(phases: readonly (readonly TaskResult[])[]): readonly TaskResult[];
+export declare function collectResults(phases: ReadonlyArray<readonly TaskResult[]>): readonly TaskResult[];
 
 /**
  * The per-unit handle a runner handler receives — wraps the unit's identity,
@@ -865,7 +865,7 @@ export declare function hasWorkflowHandlers(workflow: WorkflowSnapshot, function
  * insertEntry([['a', 1], ['b', 2]], 1, 'c', 3) // [['a', 1], ['c', 3], ['b', 2]]
  * ```
  */
-export declare function insertEntry<T>(entries: readonly (readonly [string, T])[], index: number, key: string, value: T): readonly (readonly [string, T])[];
+export declare function insertEntry<T>(entries: ReadonlyArray<readonly [string, T]>, index: number, key: string, value: T): ReadonlyArray<readonly [string, T]>;
 
 /** Test the workflow lifecycle vocabulary. */
 export declare function isLifecycleStatus(value: unknown): value is LifecycleStatus;
@@ -943,8 +943,9 @@ export declare function isWorkflowSnapshot(value: unknown): value is WorkflowSna
  * name + doc while the vocabulary lives in one place (AGENTS §4.4 "one concept = one
  * word"). It also types the single runtime terminal check
  * {@link import('./helpers.js').isTerminalStatus} — every tier's value is a
- * `LifecycleStatus`, so the one predicate accepts them all. The tiers stay distinct
- * types (a phase status is not a task status) even though they currently share a body.
+ * `LifecycleStatus`, so the one predicate accepts them all. The three tiers are direct
+ * aliases, not branded types, so TypeScript accepts any one of them wherever another is
+ * expected. Each name documents which tier a value came from; it does not enforce it.
  */
 export declare type LifecycleStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'stopped';
 
@@ -1024,7 +1025,7 @@ export declare class MemoryWorkflowStore implements WorkflowStoreInterface {
  * moveEntry([['a', 1], ['b', 2], ['c', 3]], 'a', 2) // [['b', 2], ['c', 3], ['a', 1]]
  * ```
  */
-export declare function moveEntry<T>(entries: readonly (readonly [string, T])[], key: string, index: number): readonly (readonly [string, T])[];
+export declare function moveEntry<T>(entries: ReadonlyArray<readonly [string, T]>, key: string, index: number): ReadonlyArray<readonly [string, T]>;
 
 /**
  * Park until `signal` aborts — a promise-parked wait (AGENTS §21), never a timer or
@@ -2104,6 +2105,16 @@ export declare interface RunnerUnit<TInput> {
  * Schedule one cancellable host operation behind an owned settlement signal.
  *
  * @remarks
+ * A defined `signal` that is not a native `AbortSignal` is refused before anything is armed, as a
+ * rejected promise carrying a {@link import('./errors.js').WorkflowError} with the `SCHEDULE` code.
+ * Rejecting rather than throwing keeps every caller on one settlement path, so a backend never has
+ * to guard the call itself.
+ *
+ * The guard is necessary but not sufficient, so linking stays contained. A `Proxy` over a native
+ * signal passes the guard and can still make linking throw from a trap, and that escape would be
+ * synchronous — the one shape every caller here is built not to expect. Containment turns it into
+ * the same `SCHEDULE` rejection, so setup has exactly one failure shape however hostile the input.
+ *
  * The completion and failure paths each own an {@link AbortController}; their native composite is
  * linked to the optional caller signal before `start` can arm host work. Scheduler backends attach
  * only to that safe composite, so caller mutation of `addEventListener` or `removeEventListener`
@@ -2115,7 +2126,8 @@ export declare interface RunnerUnit<TInput> {
  *
  * @param start - Arm host work and return its cancellation closure
  * @param signal - Optional caller cancellation signal
- * @returns A promise settled exactly once by completion, host failure, or caller abort
+ * @returns A promise settled exactly once by an invalid-signal refusal, completion, host failure,
+ *   or caller abort
  */
 export declare function scheduleHost(start: (complete: () => void, failure: (error: unknown) => void) => () => void, signal?: AbortSignal): Promise<void>;
 
@@ -3138,9 +3150,11 @@ export declare interface WorkflowDefinition {
  *
  * @remarks
  * Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
- * offending node id / status. Raised for an illegal lifecycle transition
+ * offending node id / status / parameter. Raised for an illegal lifecycle transition
  * (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
- * boundary (`RESTORE`), or a refused structural/activity edit (`MUTATION`).
+ * boundary (`RESTORE`), a refused structural/activity edit (`MUTATION`), or a host
+ * schedule refused before arming because the caller's `signal` is not a native
+ * `AbortSignal` (`SCHEDULE`, delivered as a rejected promise).
  */
 export declare class WorkflowError extends Error {
     readonly code: WorkflowErrorCode;
@@ -3170,8 +3184,13 @@ export declare class WorkflowError extends Error {
  *   {@link TaskManagerInterface.append} / {@link PhaseManagerInterface.append} duplicate-id
  *   guard (both genuine programmer-error paths, AGENTS §12). The error `context` names
  *   the offending id / index / status.
+ * - `SCHEDULE` — {@link import('./helpers.js').scheduleHost} refused to arm host work
+ *   because the caller passed a `signal` that is not a native `AbortSignal`. The refusal
+ *   is a REJECTED promise, never a synchronous throw, so every scheduler backend settles
+ *   the same way whatever the caller passed. The error `context` names the offending
+ *   parameter (`signal`) and the `typeof` the caller supplied.
  */
-export declare type WorkflowErrorCode = 'TRANSITION' | 'RESTORE' | 'MUTATION';
+export declare type WorkflowErrorCode = 'TRANSITION' | 'RESTORE' | 'MUTATION' | 'SCHEDULE';
 
 /**
  * The push observation surface (AGENTS §13) of the workflow entity (W-b) — the

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { createAbort, linkSignal } from "@orkestrel/abort";
+import { createAbort, isAbortSignal, linkSignal } from "@orkestrel/abort";
 import { arrayShape, attempt, cloneJSONRecord, cloneJSONValue, compileGuard, createContract, integerShape, isArray, isBoolean, isContractError, isFiniteNumber, isFunction, isInteger, isJSONValue, isNonEmptyString, isRecord, literalShape, objectShape, optionalShape, rawShape, stringShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { Emitter } from "@orkestrel/emitter";
@@ -109,6 +109,51 @@ var DEFAULT_PHASE_CONCURRENCY = 1024;
 */
 var MAX_TIMER_MS = 2147483647;
 //#endregion
+//#region src/core/errors.ts
+/**
+* An error raised by the workflow runtime.
+*
+* @remarks
+* Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
+* offending node id / status / parameter. Raised for an illegal lifecycle transition
+* (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
+* boundary (`RESTORE`), a refused structural/activity edit (`MUTATION`), or a host
+* schedule refused before arming because the caller's `signal` is not a native
+* `AbortSignal` (`SCHEDULE`, delivered as a rejected promise).
+*/
+var WorkflowError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "WorkflowError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link WorkflowError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link WorkflowError}
+*
+* @example
+* ```ts
+* try {
+* 	task.complete('done')
+* } catch (error) {
+* 	if (isWorkflowError(error) && error.code === 'TRANSITION') retry()
+* }
+* ```
+*/
+function isWorkflowError(value) {
+	try {
+		return value instanceof WorkflowError;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/core/helpers.ts
 /**
 * Capture every top-level {@link WorkflowOptions} value exactly once into an owned plain bag.
@@ -671,6 +716,16 @@ function createDeferred() {
 * Schedule one cancellable host operation behind an owned settlement signal.
 *
 * @remarks
+* A defined `signal` that is not a native `AbortSignal` is refused before anything is armed, as a
+* rejected promise carrying a {@link import('./errors.js').WorkflowError} with the `SCHEDULE` code.
+* Rejecting rather than throwing keeps every caller on one settlement path, so a backend never has
+* to guard the call itself.
+*
+* The guard is necessary but not sufficient, so linking stays contained. A `Proxy` over a native
+* signal passes the guard and can still make linking throw from a trap, and that escape would be
+* synchronous — the one shape every caller here is built not to expect. Containment turns it into
+* the same `SCHEDULE` rejection, so setup has exactly one failure shape however hostile the input.
+*
 * The completion and failure paths each own an {@link AbortController}; their native composite is
 * linked to the optional caller signal before `start` can arm host work. Scheduler backends attach
 * only to that safe composite, so caller mutation of `addEventListener` or `removeEventListener`
@@ -682,16 +737,18 @@ function createDeferred() {
 *
 * @param start - Arm host work and return its cancellation closure
 * @param signal - Optional caller cancellation signal
-* @returns A promise settled exactly once by completion, host failure, or caller abort
+* @returns A promise settled exactly once by an invalid-signal refusal, completion, host failure,
+*   or caller abort
 */
 function scheduleHost(start, signal) {
+	if (signal !== void 0 && !isAbortSignal(signal)) return Promise.reject(new WorkflowError("SCHEDULE", "scheduleHost signal must be an AbortSignal", { signal: typeof signal }));
 	const completion = new AbortController();
 	const failed = new AbortController();
 	let settled;
 	try {
 		settled = linkSignal(AbortSignal.any([completion.signal, failed.signal]), signal);
-	} catch (error) {
-		return Promise.reject(error);
+	} catch {
+		return Promise.reject(new WorkflowError("SCHEDULE", "scheduleHost could not link the caller signal", { signal: typeof signal }));
 	}
 	if (settled.aborted) return Promise.reject(settled.reason);
 	return new Promise((resolve, reject) => {
@@ -814,49 +871,6 @@ var Scheduler = class {
 	}
 };
 //#endregion
-//#region src/core/errors.ts
-/**
-* An error raised by the workflow runtime.
-*
-* @remarks
-* Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
-* offending node id / status. Raised for an illegal lifecycle transition
-* (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
-* boundary (`RESTORE`), or a refused structural/activity edit (`MUTATION`).
-*/
-var WorkflowError = class extends Error {
-	code;
-	context;
-	constructor(code, message, context) {
-		super(message);
-		this.name = "WorkflowError";
-		this.code = code;
-		if (context !== void 0) this.context = context;
-	}
-};
-/**
-* Narrow an unknown caught value to a {@link WorkflowError}.
-*
-* @param value - The value to test (typically a `catch` binding)
-* @returns `true` when `value` is a {@link WorkflowError}
-*
-* @example
-* ```ts
-* try {
-* 	task.complete('done')
-* } catch (error) {
-* 	if (isWorkflowError(error) && error.code === 'TRANSITION') retry()
-* }
-* ```
-*/
-function isWorkflowError(value) {
-	try {
-		return value instanceof WorkflowError;
-	} catch {
-		return false;
-	}
-}
-//#endregion
 //#region src/core/validators.ts
 /** Test the workflow lifecycle vocabulary. */
 function isLifecycleStatus(value) {