@blokjs/shared 0.2.1 → 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/BlokError.d.ts

@@ -0,0 +1,196 @@
+import GlobalError from "./GlobalError";
+/**
+ * The categories every Blok node error falls into.
+ *
+ * Mirror of the proto `blok.runtime.v1.ErrorCategory` enum. Stored as string
+ * values so JSON payloads (e.g. `GlobalError.context.json`) are human-readable.
+ */
+export declare const ErrorCategory: {
+    readonly VALIDATION: "VALIDATION";
+    readonly CONFIGURATION: "CONFIGURATION";
+    readonly DEPENDENCY: "DEPENDENCY";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly PERMISSION: "PERMISSION";
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly CANCELLED: "CANCELLED";
+    readonly INTERNAL: "INTERNAL";
+    readonly PROTOCOL: "PROTOCOL";
+    readonly DATA: "DATA";
+};
+export type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+/** How severe an error is. Default for thrown errors is `ERROR`. */
+export declare const ErrorSeverity: {
+    readonly INFO: "INFO";
+    readonly WARN: "WARN";
+    readonly ERROR: "ERROR";
+    readonly FATAL: "FATAL";
+};
+export type ErrorSeverity = (typeof ErrorSeverity)[keyof typeof ErrorSeverity];
+/**
+ * Default HTTP status per error category.
+ *
+ * Single source of truth — the runner uses these on `GlobalError.context.code`
+ * and HTTP triggers use them as the response status. Override per-error via
+ * `BlokErrorOpts.httpStatus`.
+ */
+export declare const DEFAULT_HTTP_STATUS: Readonly<Record<ErrorCategory, number>>;
+/** Default retryable hint per error category. */
+export declare const DEFAULT_RETRYABLE: Readonly<Record<ErrorCategory, boolean>>;
+/**
+ * The plain-data shape of a Blok node error.
+ *
+ * 1:1 mirror of the proto `blok.runtime.v1.NodeError` message in JSON form.
+ * The runner-side gRPC codec converts between this shape and the proto type;
+ * this module has no gRPC dependency.
+ */
+export interface NodeErrorPayload {
+    /** Stable machine identifier — see `docs/error-codes.md`. */
+    code: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    /** Node name that produced this error (auto-filled by SDKs). */
+    node: string;
+    /** SDK identifier, e.g. "blok-python3" (auto-filled). */
+    sdk: string;
+    sdkVersion: string;
+    /** Runtime kind, e.g. "runtime.python3" (auto-filled). */
+    runtimeKind: string;
+    /** ISO 8601 timestamp of the error. */
+    at: string;
+    message: string;
+    description: string;
+    remediation: string;
+    docUrl: string;
+    /** Flattened cause chain — outermost cause first. */
+    causes: NodeErrorPayload[];
+    stack: string;
+    /** Bounded slice of resolved inputs/state at error time. */
+    contextSnapshot: unknown;
+    httpStatus: number;
+    retryable: boolean;
+    retryAfterMs: number;
+    /** Category-specific structured details (Zod issues, SQL state, etc.). */
+    details: unknown;
+}
+/**
+ * Constructor options for {@link BlokError}.
+ *
+ * `code`, `message`, and the implicit `category` (via the factory method) are
+ * the seven required fields that, combined with auto-filled origin, make every
+ * error self-describing.
+ */
+export interface BlokErrorOpts {
+    /** Stable machine identifier (e.g. "POSTGRES_CONNECT_TIMEOUT"). */
+    code: string;
+    /** One-sentence human summary. */
+    message: string;
+    /** Multi-paragraph context: what was tried, why it failed. */
+    description?: string;
+    /** Suggested next step for the developer. */
+    remediation?: string;
+    /** Optional link to documentation explaining this code. */
+    docUrl?: string;
+    /** Underlying cause — any Error or BlokError. */
+    cause?: Error | BlokError;
+    /** Override default retryable hint. */
+    retryable?: boolean;
+    /** Suggested wait time before retrying. */
+    retryAfterMs?: number;
+    /** Category-specific structured details. */
+    details?: unknown;
+    /** Bounded slice of inputs/state at error time. */
+    contextSnapshot?: unknown;
+    /** Override the default HTTP status for this category. */
+    httpStatus?: number;
+    /** Override the default severity (`ERROR`). */
+    severity?: ErrorSeverity;
+    /** Override the auto-filled node name. */
+    node?: string;
+    /** Override the auto-filled SDK name. */
+    sdk?: string;
+    /** Override the auto-filled SDK version. */
+    sdkVersion?: string;
+    /** Override the auto-filled runtime kind. */
+    runtimeKind?: string;
+}
+/**
+ * Structured error type for Blok nodes. Extends {@link GlobalError} so it
+ * remains fully compatible with existing `instanceof GlobalError` checks and
+ * `GlobalError.context` consumers (HTTP trigger, RunTracker, Studio).
+ *
+ * Use the static factory methods (`BlokError.validation`,
+ * `BlokError.dependency`, etc.) — direct construction is private.
+ *
+ * Auto-fills `name`, `stack`, and `at`. The runner enriches `node`, `sdk`,
+ * `sdkVersion`, and `runtimeKind` when the error is sourced from a runtime
+ * adapter; module nodes can override via {@link BlokErrorOpts}.
+ *
+ * @example
+ *   throw BlokError.dependency({
+ *     code: "POSTGRES_CONNECT_TIMEOUT",
+ *     message: "Could not connect to Postgres within 5s",
+ *     description: `Tried host=${host} port=${port}; timeout=${dur}ms`,
+ *     remediation: "Check DATABASE_URL env var and network reachability",
+ *     cause: err,
+ *   });
+ */
+export default class BlokError extends GlobalError {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly errorCode: string;
+    readonly description: string;
+    readonly remediation: string;
+    readonly docUrl: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs: number;
+    readonly details: unknown;
+    readonly contextSnapshot: unknown;
+    readonly causes: ReadonlyArray<NodeErrorPayload>;
+    readonly at: Date;
+    readonly sdk: string;
+    readonly sdkVersion: string;
+    readonly runtimeKind: string;
+    readonly httpStatus: number;
+    readonly nodeName: string;
+    private constructor();
+    static validation(opts: BlokErrorOpts): BlokError;
+    static configuration(opts: BlokErrorOpts): BlokError;
+    static dependency(opts: BlokErrorOpts): BlokError;
+    static timeout(opts: BlokErrorOpts): BlokError;
+    static permission(opts: BlokErrorOpts): BlokError;
+    static rateLimit(opts: BlokErrorOpts): BlokError;
+    static notFound(opts: BlokErrorOpts): BlokError;
+    static conflict(opts: BlokErrorOpts): BlokError;
+    static cancelled(opts: BlokErrorOpts): BlokError;
+    static internal(opts: BlokErrorOpts): BlokError;
+    static protocol(opts: BlokErrorOpts): BlokError;
+    static data(opts: BlokErrorOpts): BlokError;
+    /**
+     * Convert any thrown value into a `BlokError`.
+     *
+     * Used by the runner's auto-wrap layer so legacy code (`throw new
+     * Error("oops")`) still produces a structured error. Categorization is
+     * heuristic — recognizes existing `BlokError` (passthrough), `GlobalError`
+     * (preserves code/json), `Error` (wraps as `INTERNAL`), and anything else
+     * (stringified as `INTERNAL`).
+     */
+    static fromUnknown(err: unknown, ctx?: {
+        node?: string;
+        sdk?: string;
+        sdkVersion?: string;
+        runtimeKind?: string;
+    }): BlokError;
+    /**
+     * Reconstruct a `BlokError` from a serialized {@link NodeErrorPayload}.
+     *
+     * Used by the runner's gRPC codec to convert proto `NodeError` messages
+     * received from SDKs back into TS-side errors.
+     */
+    static fromJSON(payload: NodeErrorPayload): BlokError;
+    /** Serialize to the canonical {@link NodeErrorPayload} shape (matches proto wire format). */
+    toJSON(): NodeErrorPayload;
+    private static flattenCauses;
+    private static causeToPayload;
+}