@orkestrel/workflow 0.0.10 → 0.0.11

package/dist/src/core/index.cjs

@@ -110,6 +110,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.
@@ -672,6 +717,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`
@@ -683,16 +738,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 && !(0, _orkestrel_abort.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 = (0, _orkestrel_abort.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) => {
@@ -815,49 +872,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) {