@blokjs/shared 0.2.2 → 0.4.0

package/__tests__/unit/utils/Mapper.test.ts

@@ -1,10 +1,12 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type Context from "../../../src/types/Context";
 import mapper from "../../../src/utils/Mapper";
+import { MapperResolutionError } from "../../../src/utils/MapperResolutionError";
 
 function createMockContext(overrides: Partial<Context> = {}): Context {
 	return {
 		id: "test-id",
+		workflow_name: "test-workflow",
 		request: { body: {}, headers: {}, query: {}, params: {} },
 		response: { data: null, error: null, success: true },
 		error: { message: "" },
@@ -18,107 +20,373 @@ function createMockContext(overrides: Partial<Context> = {}): Context {
 	} as Context;
 }
 
+/**
+ * Test helper — set the resolution mode for the duration of one test.
+ * Resets to the v0.3.x default (`"warn"`) after each case.
+ */
+function setMode(mode: "warn" | "strict" | "silent"): void {
+	process.env.BLOK_MAPPER_MODE = mode;
+}
+
 describe("Mapper", () => {
 	beforeEach(() => {
 		vi.restoreAllMocks();
+		// Reset to the v0.3.x default ("warn"). Assignment to undefined
+		// keeps biome's `noDelete` rule happy without changing semantics —
+		// `process.env.X = undefined` makes `process.env.X` evaluate to
+		// the string `"undefined"` in Node, but Mapper's `readMode()`
+		// treats anything that isn't "strict" or "silent" as warn, so
+		// the default is preserved.
+		process.env.BLOK_MAPPER_MODE = undefined;
 	});
 
-	describe("replaceString()", () => {
-		it("should replace ${key} with data value", () => {
+	afterEach(() => {
+		process.env.BLOK_MAPPER_MODE = undefined;
+	});
+
+	// =========================================================================
+	// Pre-existing behavior — replaceString happy paths (preserved across rewrite)
+	// =========================================================================
+
+	describe("replaceString() — happy paths", () => {
+		it("replaces ${key} with data value", () => {
 			const ctx = createMockContext();
 			const data = { name: "John" };
 			const result = mapper.replaceString("Hello ${name}", ctx, data);
 			expect(result).toBe("Hello John");
 		});
 
-		it("should replace multiple placeholders", () => {
+		it("replaces multiple placeholders", () => {
 			const ctx = createMockContext();
 			const data = { first: "John", last: "Doe" };
 			const result = mapper.replaceString("${first} ${last}", ctx, data);
 			expect(result).toBe("John Doe");
 		});
 
-		it("should handle nested data access via lodash.get", () => {
+		it("handles nested data access via lodash.get", () => {
 			const ctx = createMockContext();
 			const data = { user: { name: "Alice" } };
 			const result = mapper.replaceString("Hi ${user.name}", ctx, data);
 			expect(result).toBe("Hi Alice");
 		});
 
-		it("should handle no matches (no ${})", () => {
+		it("handles no matches (no ${})", () => {
 			const ctx = createMockContext();
 			const result = mapper.replaceString("plain text", ctx, {});
 			expect(result).toBe("plain text");
 		});
 
-		it("should execute js/ prefix expressions", () => {
+		it("executes js/ prefix expressions", () => {
 			const ctx = createMockContext();
 			const result = mapper.replaceString("js/1 + 2", ctx, {});
 			expect(result).toBe(3);
 		});
 
-		it("should pass through non-js strings", () => {
+		it("passes through non-js strings", () => {
 			const ctx = createMockContext();
 			const result = mapper.replaceString("hello world", ctx, {});
 			expect(result).toBe("hello world");
 		});
+	});
+
+	// =========================================================================
+	// Bug fixes shipped with the rewrite (v0.3.x)
+	// =========================================================================
+
+	describe("replaceString() — bug fixes (v0.3.x)", () => {
+		it("preserves falsy-but-valid lookup values (was: || fell through to runJs)", () => {
+			const ctx = createMockContext();
+			// Pre-v0.3.x: `_.get(data, key) || runJs(key)` — when lookup
+			// returned 0, the `||` fell through to runJs (which would throw
+			// for "count" not being in scope). Now `=== undefined` check
+			// preserves the 0.
+			expect(mapper.replaceString("${count}", ctx, { count: 0 })).toBe("0");
+			expect(mapper.replaceString("${flag}", ctx, { flag: false })).toBe("false");
+			expect(mapper.replaceString("${empty}", ctx, { empty: "" })).toBe("");
+		});
 
-		it("should handle errors silently in placeholder replacement", () => {
-			const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+		it("JSON-encodes object values in interpolation (was: '[object Object]')", () => {
 			const ctx = createMockContext();
-			// An expression that throws inside Function()
-			const result = mapper.replaceString("${undefinedVar.deep.access}", ctx, {});
-			// Should not throw, returns string with attempted replacement
-			expect(result).toBeTypeOf("string");
-			consoleSpy.mockRestore();
+			const data = { user: { id: 1, name: "Alice" } };
+			const result = mapper.replaceString("payload=${user}", ctx, data);
+			// Pre-v0.3.x: `value as string` → "[object Object]". Now JSON.
+			expect(result).toBe('payload={"id":1,"name":"Alice"}');
+		});
+
+		it("renders null/undefined interpolation values as empty string", () => {
+			const ctx = createMockContext();
+			const result = mapper.replaceString("v=${x}", ctx, { x: null });
+			expect(result).toBe("v=");
+		});
+
+		it("strips only the `js/` prefix (slice(3) vs replace('js/', ''))", () => {
+			const ctx = createMockContext();
+			// A fabricated edge case — an expression that contains the
+			// substring "js/" later. Pre-v0.3.x's `replace("js/", "")`
+			// would strip the wrong occurrence and break the eval.
+			// (The expression here evaluates safely; we just check
+			// the prefix-stripping doesn't double-strip.)
+			const result = mapper.replaceString('js/"prefix:" + "js/inside"', ctx, {});
+			expect(result).toBe("prefix:js/inside");
+		});
+
+		it("provides symmetric scope (func + vars) inside ${...} expressions", () => {
+			// Pre-v0.3.x: `${func.X}` threw because runJs was called with
+			// only 3 args. Now func/vars are bound in both syntaxes for
+			// consistency with `js/...`.
+			const ctx = createMockContext({ vars: { count: 7 } });
+			const result = mapper.replaceString("${vars.count}", ctx, {});
+			expect(result).toBe("7");
 		});
 	});
 
+	// =========================================================================
+	// Failure modes (BLOK_MAPPER_MODE)
+	// =========================================================================
+
+	describe('mode = "warn" (default) — log + pass-through', () => {
+		it("logs an actionable warning via ctx.logger.logLevel", () => {
+			const logLevel = vi.fn();
+			const ctx = createMockContext({
+				logger: { log: vi.fn(), logLevel, error: vi.fn() } as unknown as Context["logger"],
+				workflow_name: "wf-X",
+			});
+			(ctx as Record<string, unknown>)._stepInfo = { name: "step-Y" };
+
+			const result = mapper.replaceString("js/ctx.req.body.bad.path", ctx, {});
+
+			// Original literal passes through (back-compat).
+			expect(result).toBe("js/ctx.req.body.bad.path");
+			// Single warn call with the structured message.
+			expect(logLevel).toHaveBeenCalledTimes(1);
+			expect(logLevel.mock.calls[0][0]).toBe("warn");
+			const message = logLevel.mock.calls[0][1] as string;
+			expect(message).toContain('step "step-Y"');
+			expect(message).toContain('workflow "wf-X"');
+			expect(message).toContain("ctx.req.body.bad.path");
+			expect(message).toContain("hint:");
+			expect(message).toContain("BLOK_MAPPER_MODE=strict");
+		});
+
+		it("falls back to console.warn when ctx.logger has neither logLevel nor log", () => {
+			const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+			// Logger object lacking logLevel + log methods.
+			const ctx = createMockContext({
+				logger: { error: vi.fn() } as unknown as Context["logger"],
+			});
+			mapper.replaceString("js/ctx.bad.access", ctx, {});
+			expect(consoleWarn).toHaveBeenCalledTimes(1);
+			expect(consoleWarn.mock.calls[0][0] as string).toContain("[blok][mapper]");
+		});
+
+		it("returns the literal placeholder for failed ${...} interpolation", () => {
+			const ctx = createMockContext({
+				logger: { log: vi.fn(), logLevel: vi.fn(), error: vi.fn() } as unknown as Context["logger"],
+			});
+			const result = mapper.replaceString("hi ${ctx.req.body.bad.path}", ctx, {});
+			// Pre-v0.3.x also did this — we preserve the back-compat.
+			expect(result).toBe("hi ${ctx.req.body.bad.path}");
+		});
+	});
+
+	describe('mode = "strict" — throws MapperResolutionError', () => {
+		it("throws on failed js/ expression with full context", () => {
+			setMode("strict");
+			const ctx = createMockContext({ workflow_name: "wf-strict" });
+			(ctx as Record<string, unknown>)._stepInfo = { name: "step-A" };
+
+			let thrown: unknown = null;
+			try {
+				mapper.replaceString("js/ctx.req.body.bad.path", ctx, {});
+			} catch (e) {
+				thrown = e;
+			}
+			expect(thrown).toBeInstanceOf(MapperResolutionError);
+			const err = thrown as MapperResolutionError;
+			expect(err.context.expression).toBe("ctx.req.body.bad.path");
+			expect(err.context.syntax).toBe("js");
+			expect(err.context.workflowName).toBe("wf-strict");
+			expect(err.context.stepName).toBe("step-A");
+			expect(err.context.cause).toBeInstanceOf(TypeError);
+		});
+
+		it("throws on failed ${...} expression", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			expect(() => mapper.replaceString("${ctx.req.body.bad.path}", ctx, {})).toThrow(MapperResolutionError);
+		});
+
+		it("does NOT throw when expression resolves successfully", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			expect(mapper.replaceString("js/1 + 2", ctx, {})).toBe(3);
+			expect(mapper.replaceString("${name}", ctx, { name: "ok" })).toBe("ok");
+		});
+	});
+
+	describe('mode = "silent" — full suppression (pre-v0.3.x behavior)', () => {
+		it("does not log via ctx.logger", () => {
+			setMode("silent");
+			const logLevel = vi.fn();
+			const log = vi.fn();
+			const ctx = createMockContext({
+				logger: { log, logLevel, error: vi.fn() } as unknown as Context["logger"],
+			});
+			const result = mapper.replaceString("js/ctx.req.body.bad.path", ctx, {});
+			expect(result).toBe("js/ctx.req.body.bad.path");
+			expect(logLevel).not.toHaveBeenCalled();
+			expect(log).not.toHaveBeenCalled();
+		});
+
+		it("does not log via console.warn", () => {
+			setMode("silent");
+			const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+			const ctx = createMockContext({ logger: undefined as unknown as Context["logger"] });
+			mapper.replaceString("js/ctx.bad", ctx, {});
+			expect(consoleWarn).not.toHaveBeenCalled();
+		});
+	});
+
+	// =========================================================================
+	// MapperResolutionError diagnostic content
+	// =========================================================================
+
+	describe("MapperResolutionError — diagnostic message quality", () => {
+		it("includes a hint for 'Cannot read properties of undefined' errors", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			let thrown: MapperResolutionError | null = null;
+			try {
+				mapper.replaceString("js/ctx.req.body.deeply.nested.value", ctx, {});
+			} catch (e) {
+				thrown = e as MapperResolutionError;
+			}
+			expect(thrown?.message).toMatch(/hint: the path/);
+			expect(thrown?.message).toMatch(/check the trigger payload/i);
+		});
+
+		it("includes a hint for ReferenceError ('not defined')", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			let thrown: MapperResolutionError | null = null;
+			try {
+				mapper.replaceString("js/unknownIdentifier.foo", ctx, {});
+			} catch (e) {
+				thrown = e as MapperResolutionError;
+			}
+			expect(thrown?.message).toMatch(/`unknownIdentifier` is not in scope/);
+			expect(thrown?.message).toMatch(/ctx, data, func, vars/);
+		});
+
+		it("includes a hint for syntax errors", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			let thrown: MapperResolutionError | null = null;
+			try {
+				mapper.replaceString("js/ctx.req.body.+", ctx, {});
+			} catch (e) {
+				thrown = e as MapperResolutionError;
+			}
+			expect(thrown?.message).toMatch(/not valid JavaScript/);
+		});
+
+		it("works with `instanceof` after JSON round-trip preservation (Object.setPrototypeOf)", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			let thrown: unknown = null;
+			try {
+				mapper.replaceString("js/ctx.req.body.x.y", ctx, {});
+			} catch (e) {
+				thrown = e;
+			}
+			expect(thrown instanceof MapperResolutionError).toBe(true);
+			expect(thrown instanceof Error).toBe(true);
+		});
+
+		it("attaches Error.cause for native cause-chain support", () => {
+			setMode("strict");
+			const ctx = createMockContext();
+			let thrown: MapperResolutionError | null = null;
+			try {
+				mapper.replaceString("js/ctx.req.body.x.y", ctx, {});
+			} catch (e) {
+				thrown = e as MapperResolutionError;
+			}
+			const e = thrown as Error & { cause?: unknown };
+			expect(e.cause).toBeDefined();
+			expect(e.cause).toBe(thrown?.context.cause);
+		});
+	});
+
+	// =========================================================================
+	// replaceObjectStrings — recursion + mutation contract
+	// =========================================================================
+
 	describe("replaceObjectStrings()", () => {
-		it("should replace string values in flat object", () => {
+		it("replaces string values in flat object", () => {
 			const ctx = createMockContext();
 			const data = { greeting: "World" };
 			const obj: Record<string, unknown> = { msg: "Hello ${greeting}" };
-			mapper.replaceObjectStrings(obj, ctx, data);
+			mapper.replaceObjectStrings(obj as Record<string, string>, ctx, data);
 			expect(obj.msg).toBe("Hello World");
 		});
 
-		it("should recursively replace nested objects", () => {
+		it("recursively replaces nested objects", () => {
 			const ctx = createMockContext();
 			const data = { val: "replaced" };
 			const obj: Record<string, unknown> = {
-				level1: {
-					level2: "value is ${val}",
-				},
+				level1: { level2: "value is ${val}" },
 			};
-			mapper.replaceObjectStrings(obj, ctx, data);
+			mapper.replaceObjectStrings(obj as Record<string, string>, ctx, data);
 			expect((obj.level1 as Record<string, unknown>).level2).toBe("value is replaced");
 		});
 
-		it("should skip non-string, non-object values", () => {
+		it("skips non-string, non-object values (null, primitives untouched)", () => {
 			const ctx = createMockContext();
-			const obj: Record<string, unknown> = { num: 42, bool: true, str: "keep" };
-			mapper.replaceObjectStrings(obj, ctx, {});
+			const obj: Record<string, unknown> = { num: 42, bool: true, str: "keep", nullish: null };
+			mapper.replaceObjectStrings(obj as Record<string, string>, ctx, {});
 			expect(obj.num).toBe(42);
 			expect(obj.bool).toBe(true);
 			expect(obj.str).toBe("keep");
+			expect(obj.nullish).toBe(null);
+		});
+
+		it("preserves the actual resolved type when assigning back to the dictionary slot", () => {
+			// `obj.count` ends up as the NUMBER 5, not the string "5",
+			// because js/ expressions return their actual evaluated type.
+			const ctx = createMockContext({ vars: { count: 5 } });
+			const obj: Record<string, unknown> = { count: "js/ctx.vars.count" };
+			mapper.replaceObjectStrings(obj as Record<string, string>, ctx, {});
+			expect(obj.count).toBe(5);
+			expect(typeof obj.count).toBe("number");
 		});
 	});
 
+	// =========================================================================
+	// jsMapper via replaceString
+	// =========================================================================
+
 	describe("jsMapper via replaceString", () => {
-		it("should access ctx in js/ expressions", () => {
+		it("accesses ctx in js/ expressions", () => {
 			const ctx = createMockContext({ vars: { count: 5 } });
 			const result = mapper.replaceString("js/ctx.vars.count", ctx, {});
 			expect(result).toBe(5);
 		});
 
-		it("should handle js/ errors silently", () => {
-			const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
-			const ctx = createMockContext();
+		it("handles js/ errors in default mode (warn) by passing through the literal", () => {
+			const ctx = createMockContext({
+				logger: { log: vi.fn(), logLevel: vi.fn(), error: vi.fn() } as unknown as Context["logger"],
+			});
 			const result = mapper.replaceString('js/throw new Error("fail")', ctx, {});
-			// Should return the original string on error
+			// Original literal passes through (back-compat).
 			expect(result).toBe('js/throw new Error("fail")');
-			consoleSpy.mockRestore();
+		});
+
+		it("returns the actual evaluated type (number, object, array) — not a string", () => {
+			const ctx = createMockContext();
+			expect(mapper.replaceString("js/[1, 2, 3]", ctx, {})).toEqual([1, 2, 3]);
+			expect(mapper.replaceString('js/({hello: "world"})', ctx, {})).toEqual({ hello: "world" });
+			expect(mapper.replaceString("js/true", ctx, {})).toBe(true);
 		});
 	});
 });

package/__tests__/unit/utils/MapperResolutionError.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { MapperResolutionError } from "../../../src/utils/MapperResolutionError";
+
+describe("MapperResolutionError", () => {
+	it("constructs with name 'MapperResolutionError'", () => {
+		const e = new MapperResolutionError("msg", { expression: "x", syntax: "js" });
+		expect(e.name).toBe("MapperResolutionError");
+	});
+
+	it("preserves the prototype chain across `instanceof` checks", () => {
+		const e = new MapperResolutionError("msg", { expression: "x", syntax: "js" });
+		expect(e instanceof MapperResolutionError).toBe(true);
+		expect(e instanceof Error).toBe(true);
+	});
+
+	it("carries the structured context object verbatim", () => {
+		const cause = new TypeError("boom");
+		const e = new MapperResolutionError("msg", {
+			expression: "ctx.req.body.id",
+			syntax: "js",
+			workflowName: "wf-1",
+			stepName: "step-2",
+			cause,
+		});
+		expect(e.context.expression).toBe("ctx.req.body.id");
+		expect(e.context.syntax).toBe("js");
+		expect(e.context.workflowName).toBe("wf-1");
+		expect(e.context.stepName).toBe("step-2");
+		expect(e.context.cause).toBe(cause);
+	});
+
+	it("attaches Error.cause when context.cause is provided (ES2022 cause-chain)", () => {
+		const cause = new Error("underlying");
+		const e = new MapperResolutionError("msg", { expression: "x", syntax: "js", cause });
+		// `cause` is set on the Error instance per spec.
+		expect((e as Error & { cause?: unknown }).cause).toBe(cause);
+	});
+
+	it("does NOT set Error.cause when context.cause is omitted", () => {
+		const e = new MapperResolutionError("msg", { expression: "x", syntax: "js" });
+		expect((e as Error & { cause?: unknown }).cause).toBeUndefined();
+	});
+
+	it("supports both syntax discriminators (js + template)", () => {
+		const a = new MapperResolutionError("msg", { expression: "ctx.x", syntax: "js" });
+		const b = new MapperResolutionError("msg", { expression: "ctx.x", syntax: "template" });
+		expect(a.context.syntax).toBe("js");
+		expect(b.context.syntax).toBe("template");
+	});
+
+	it("captures the original message verbatim (multi-line OK)", () => {
+		const msg = "[blok][mapper] Failed to resolve `js/x`\n  underlying: bad\n  hint: try this";
+		const e = new MapperResolutionError(msg, { expression: "x", syntax: "js" });
+		expect(e.message).toBe(msg);
+	});
+
+	it("makes context fields readonly at the type level (compile-time check)", () => {
+		// This test exists for documentation — TS rejects mutation on
+		// `readonly` fields at compile time. At runtime, the object
+		// is plain. We assert the shape, not enforcement.
+		const e = new MapperResolutionError("msg", { expression: "x", syntax: "js" });
+		expect(Object.isFrozen(e.context)).toBe(false); // readonly is type-level only
+	});
+});

package/dist/NodeBase.d.ts

@@ -40,6 +40,64 @@ export default abstract class NodeBase {
      * Only `ctx.prev` carries the result to the immediately next step.
      */
     ephemeral: boolean;
+    /**
+     * Optional cache key for this step's result. When set, the runner consults
+     * the idempotency cache before executing — a hit returns the cached result
+     * (and emits a NODE_CACHED event); a miss runs the step and caches its
+     * result on success. Cache namespace is (workflowName, name, idempotencyKey).
+     *
+     * Author-facing values may be a literal string ("user-123") or a $ proxy
+     * expression compiled to `js/ctx....`. The runner resolves the expression
+     * against the live ctx at run time before consulting the cache.
+     */
+    idempotencyKey?: string;
+    /**
+     * Optional cache lifetime in milliseconds. Defaults to 24 hours
+     * (86_400_000) when undefined. Pass 0 to mark a stored result as
+     * immediately expired (effectively disables caching for this step).
+     */
+    idempotencyKeyTTL?: number;
+    /**
+     * Optional retry configuration with capped exponential backoff. When
+     * undefined, the step runs at most once (matches pre-v0.3.x behaviour).
+     * Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+     */
+    retry?: {
+        maxAttempts: number;
+        minTimeoutInMs?: number;
+        maxTimeoutInMs?: number;
+        factor?: number;
+    };
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout in milliseconds.
+     * When set, `RunnerSteps` wraps each `step.process()` in a setTimeout-
+     * based Promise.race. On timeout, throws `StepTimeoutError` (which the
+     * retry loop treats as any other error). On final-attempt timeout,
+     * the run auto-flips to `"timedOut"` status. When undefined, the
+     * step runs without a per-attempt cap (matches pre-quick-wins
+     * behaviour).
+     *
+     * Originally set as a duration string or number on the step schema;
+     * `Configuration.getSteps` converts to milliseconds via
+     * `parseDuration` before assigning here.
+     */
+    maxDurationMs?: number;
+    /**
+     * Name of the workflow to invoke when this step runs. When set, the
+     * step's `node` ref is `"@blokjs/subworkflow"` (a sentinel) and the
+     * runner resolves it to a `SubworkflowNode` that looks up the child
+     * by this name in the `WorkflowRegistry` singleton.
+     */
+    subworkflow?: string;
+    /**
+     * If true (default), the parent step blocks until the child workflow
+     * completes. The child's `ctx.response` becomes the parent step's
+     * output (lands on `state[<id>]` like any other step).
+     *
+     * `wait: false` (fire-and-forget) is rejected at workflow load time
+     * in v0.3.x — the schema includes a deferred-feature error message.
+     */
+    wait?: boolean;
     process(ctx: Context, step?: Step): Promise<ResponseContext>;
     processFlow(ctx: Context): Promise<ResponseContext>;
     abstract run(ctx: Context): Promise<ResponseContext>;

package/dist/NodeBase.js

@@ -1,6 +1,7 @@
 import _ from "lodash";
 import GlobalError from "./GlobalError";
 import mapper from "./utils/Mapper";
+import { MapperResolutionError } from "./utils/MapperResolutionError";
 export default class NodeBase {
     flow = false;
     name = "";
@@ -39,6 +40,75 @@ export default class NodeBase {
      * Only `ctx.prev` carries the result to the immediately next step.
      */
     ephemeral = false;
+    // =========================================================================
+    // V2 idempotency cache + retry knobs — populated by Configuration.getSteps
+    // from the step definition. Read by RunnerSteps before delegating to
+    // `step.process()`. Caching layers ABOVE PersistenceHelper.applyStepOutput;
+    // retry wraps the same call site.
+    //
+    // Mirrors the Zod schema in `@blokjs/helper/src/types/StepOpts.ts`. Kept
+    // as a structural interface here to avoid a runtime dep from shared on
+    // helper.
+    // =========================================================================
+    /**
+     * Optional cache key for this step's result. When set, the runner consults
+     * the idempotency cache before executing — a hit returns the cached result
+     * (and emits a NODE_CACHED event); a miss runs the step and caches its
+     * result on success. Cache namespace is (workflowName, name, idempotencyKey).
+     *
+     * Author-facing values may be a literal string ("user-123") or a $ proxy
+     * expression compiled to `js/ctx....`. The runner resolves the expression
+     * against the live ctx at run time before consulting the cache.
+     */
+    idempotencyKey;
+    /**
+     * Optional cache lifetime in milliseconds. Defaults to 24 hours
+     * (86_400_000) when undefined. Pass 0 to mark a stored result as
+     * immediately expired (effectively disables caching for this step).
+     */
+    idempotencyKeyTTL;
+    /**
+     * Optional retry configuration with capped exponential backoff. When
+     * undefined, the step runs at most once (matches pre-v0.3.x behaviour).
+     * Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+     */
+    retry;
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout in milliseconds.
+     * When set, `RunnerSteps` wraps each `step.process()` in a setTimeout-
+     * based Promise.race. On timeout, throws `StepTimeoutError` (which the
+     * retry loop treats as any other error). On final-attempt timeout,
+     * the run auto-flips to `"timedOut"` status. When undefined, the
+     * step runs without a per-attempt cap (matches pre-quick-wins
+     * behaviour).
+     *
+     * Originally set as a duration string or number on the step schema;
+     * `Configuration.getSteps` converts to milliseconds via
+     * `parseDuration` before assigning here.
+     */
+    maxDurationMs;
+    // =========================================================================
+    // V2 sub-workflow knobs — populated by Configuration.getSteps for steps
+    // that invoke another workflow (`subworkflow: "<name>"` shape). Read by
+    // `SubworkflowNode.run()` to look up the child workflow in the
+    // WorkflowRegistry. Mirrors the Zod schema in `@blokjs/helper`.
+    // =========================================================================
+    /**
+     * Name of the workflow to invoke when this step runs. When set, the
+     * step's `node` ref is `"@blokjs/subworkflow"` (a sentinel) and the
+     * runner resolves it to a `SubworkflowNode` that looks up the child
+     * by this name in the `WorkflowRegistry` singleton.
+     */
+    subworkflow;
+    /**
+     * If true (default), the parent step blocks until the child workflow
+     * completes. The child's `ctx.response` becomes the parent step's
+     * output (lands on `state[<id>]` like any other step).
+     *
+     * `wait: false` (fire-and-forget) is rejected at workflow load time
+     * in v0.3.x — the schema includes a deferred-feature error message.
+     */
+    wait;
     async process(ctx, step) {
         let response = {
             success: true,
@@ -106,7 +176,15 @@ export default class NodeBase {
                 mapper.replaceObjectStrings(newObj, ctx, data);
         }
         catch (e) {
-            console.log("MAPPER ERROR", e);
+            // `MapperResolutionError` (strict mode) carries full diagnostic
+            // context — let it escape so the step's error envelope surfaces
+            // the workflow / step / expression that failed.
+            if (e instanceof MapperResolutionError)
+                throw e;
+            // Anything else here is an UNEXPECTED bug in the mapper itself
+            // (recursion fault, OOM, logger crash). Surface loudly via
+            // stderr WITH the stack trace — never silently swallow.
+            console.error("[blok][mapper] unexpected error during input resolution:", e);
         }
         return newObj;
     };

package/dist/NodeBase.js.map

@@ -1 +1 @@
-{"version":3,"file":"NodeBase.js","sourceRoot":"","sources":["../src/NodeBase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"NodeBase.js","sourceRoot":"","sources":["../src/NodeBase.ts"],"names":[],"mappings":"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"}