@blokjs/shared 0.2.2 → 0.6.0

package/__tests__/unit/NodeBase.test.ts

@@ -14,7 +14,10 @@ class TestNode extends NodeBase {
 	}
 }
 
-function createTestContext(overrides: Partial<Context> = {}): Context {
+// Loose `Record<string, unknown>` overrides so tests can pass shapes that
+// don't strictly match `Partial<Context>` (e.g. `config: { "<node>": ... }`,
+// which is the runtime layout but isn't reflected in the typed `ConfigContext`).
+function createTestContext(overrides: Record<string, unknown> = {}): Context {
 	return {
 		id: "test-ctx",
 		request: { body: {}, headers: {}, query: {}, params: {} },
@@ -27,7 +30,7 @@ function createTestContext(overrides: Partial<Context> = {}): Context {
 		eventLogger: null,
 		_PRIVATE_: null,
 		...overrides,
-	} as Context;
+	} as unknown as Context;
 }
 
 describe("NodeBase", () => {
@@ -46,10 +49,8 @@ describe("NodeBase", () => {
 			expect(n.name).toBe("");
 			expect(n.active).toBe(true);
 			expect(n.stop).toBe(false);
-			// set_var defaults to undefined (NOT false). false short-circuits
-			// PersistenceHelper.applyStepOutput and silently disables v2's
-			// default-store rule for every step that didn't explicitly set it.
-			expect(n.set_var).toBeUndefined();
+			expect(n.ephemeral).toBe(false);
+			expect(n.spread).toBe(false);
 			expect(n.contentType).toBe("");
 		});
 	});
@@ -162,7 +163,7 @@ describe("NodeBase", () => {
 
 		it("should access data parameter", () => {
 			const ctx = createTestContext();
-			const result = node.runJs("data.x", ctx, { x: 42 });
+			const result = node.runJs("data.x", ctx, { x: 42 } as unknown as Record<string, string>);
 			expect(result).toBe(42);
 		});
 
@@ -215,7 +216,7 @@ describe("NodeBase", () => {
 	describe("blueprintMapper()", () => {
 		it("should handle string input", () => {
 			const ctx = createTestContext();
-			const result = node.blueprintMapper("plain text", ctx);
+			const result = node.blueprintMapper("plain text" as unknown as Record<string, string>, ctx);
 			expect(result).toBe("plain text");
 		});
 
@@ -230,7 +231,7 @@ describe("NodeBase", () => {
 			const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
 			const ctx = createTestContext();
 			// null will cause mapper to fail
-			const result = node.blueprintMapper(null as unknown as Record<string, unknown>, ctx);
+			const result = node.blueprintMapper(null as unknown as Record<string, string>, ctx);
 			// Should not throw
 			expect(result).toBeNull();
 			consoleSpy.mockRestore();

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

@@ -1,10 +1,13 @@
-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 type ParamsDictionary from "../../../src/types/ParamsDictionary";
 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 +21,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);
+			const result = mapper.replaceString("Hi ${user.name}", ctx, data as unknown as ParamsDictionary);
 			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 } as unknown as ParamsDictionary)).toBe("0");
+			expect(mapper.replaceString("${flag}", ctx, { flag: false } as unknown as ParamsDictionary)).toBe("false");
+			expect(mapper.replaceString("${empty}", ctx, { empty: "" } as unknown as ParamsDictionary)).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 as unknown as ParamsDictionary);
+			// 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 } as unknown as ParamsDictionary);
+			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" } as unknown as ParamsDictionary)).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

@@ -13,17 +13,6 @@ export default abstract class NodeBase {
     active: boolean;
     stop: boolean;
     originalConfig: ParamsDictionary;
-    /**
-     * @deprecated v2 default-stores every step's output. `set_var: true` is
-     * a no-op (default behaviour); `set_var: false` is normalized to
-     * `ephemeral: true` at workflow load time. Reading this field is still
-     * supported for legacy code paths but new code should rely on `ephemeral`.
-     *
-     * Default is `undefined` (NOT `false`) — `false` here would short-circuit
-     * `PersistenceHelper.applyStepOutput` and disable the v2 default-store
-     * rule for every step that didn't explicitly set the field.
-     */
-    set_var?: boolean;
     /**
      * Alternative state key for this step's output. When set, the runner
      * stores result.data at `ctx.state[as]` instead of `ctx.state[name]`.
@@ -40,6 +29,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>;