@blokjs/shared 2.0.0 → 2.1.0

package/dist/BlokError.d.ts

@@ -204,7 +204,9 @@ export default class BlokError extends GlobalError {
 export declare const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 /**
  * True when `err` is the ADR-0015 **input-validation gate's** deterministic
- * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag.
+ * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag
+ * (in practice a {@link WorkflowInputValidationError}; the tag is what's matched
+ * so an error that crossed a serialization boundary still classifies).
  *
  * Triggers consult this to route the error to DLQ / drop / a 4xx response
  * instead of a poison-message loop (worker burning its retry budget, pub/sub
@@ -217,3 +219,32 @@ export declare const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
  * never surfaced by the webhook 4xx path.
  */
 export declare function isNonRetryableValidationError(err: unknown): boolean;
+/** One Zod issue, flattened to plain data for the wire. */
+export interface WorkflowInputValidationIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/** What the ADR-0015 gate knows about the rejection. */
+export interface WorkflowInputValidationInfo {
+    /** The workflow whose declared `input` schema rejected the payload. */
+    workflowName: string;
+    /** Every Zod issue, in schema order. */
+    issues: WorkflowInputValidationIssue[];
+}
+/**
+ * ADR 0015 — thrown by the input gate in `TriggerBase.run()` when the invoking
+ * trigger's payload fails the workflow's declared `input` Zod.
+ *
+ * Named + exported so callers can `instanceof` it, matching the vocabulary of
+ * the other gate errors (`ConcurrencyLimitError`, `QueueExpiredError`,
+ * `MapperResolutionError`). It extends `GlobalError` — carrying code 400, the
+ * {@link WORKFLOW_INPUT_VALIDATION} tag on `context.name`, and the structured
+ * `validation_errors` json — so every existing transport translation
+ * (HTTP 400, MCP `isError`, gRPC error status, worker/pubsub/webhook DLQ
+ * routing via {@link isNonRetryableValidationError}) keeps working untouched.
+ */
+export declare class WorkflowInputValidationError extends GlobalError {
+    readonly info: WorkflowInputValidationInfo;
+    constructor(info: WorkflowInputValidationInfo);
+}

package/dist/BlokError.js

@@ -335,7 +335,9 @@ export default class BlokError extends GlobalError {
 export const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 /**
  * True when `err` is the ADR-0015 **input-validation gate's** deterministic
- * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag.
+ * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag
+ * (in practice a {@link WorkflowInputValidationError}; the tag is what's matched
+ * so an error that crossed a serialization boundary still classifies).
  *
  * Triggers consult this to route the error to DLQ / drop / a 4xx response
  * instead of a poison-message loop (worker burning its retry budget, pub/sub
@@ -350,3 +352,34 @@ export const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 export function isNonRetryableValidationError(err) {
     return err instanceof GlobalError && err.context.name === WORKFLOW_INPUT_VALIDATION;
 }
+/**
+ * ADR 0015 — thrown by the input gate in `TriggerBase.run()` when the invoking
+ * trigger's payload fails the workflow's declared `input` Zod.
+ *
+ * Named + exported so callers can `instanceof` it, matching the vocabulary of
+ * the other gate errors (`ConcurrencyLimitError`, `QueueExpiredError`,
+ * `MapperResolutionError`). It extends `GlobalError` — carrying code 400, the
+ * {@link WORKFLOW_INPUT_VALIDATION} tag on `context.name`, and the structured
+ * `validation_errors` json — so every existing transport translation
+ * (HTTP 400, MCP `isError`, gRPC error status, worker/pubsub/webhook DLQ
+ * routing via {@link isNonRetryableValidationError}) keeps working untouched.
+ */
+export class WorkflowInputValidationError extends GlobalError {
+    info;
+    constructor(info) {
+        const summary = info.issues.map((i) => `${i.path.join(".") || "(root)"} (${i.message})`).join(", ");
+        super(`Input validation failed for workflow '${info.workflowName}': ${summary}`);
+        // `GlobalError`'s own constructor pins the prototype to GlobalError.prototype,
+        // so a subclass MUST re-pin or `instanceof WorkflowInputValidationError` is false.
+        Object.setPrototypeOf(this, WorkflowInputValidationError.prototype);
+        this.name = "WorkflowInputValidationError";
+        this.info = info;
+        this.setCode(400);
+        this.setName(WORKFLOW_INPUT_VALIDATION);
+        this.setJson({
+            error: "Input validation failed",
+            workflowName: info.workflowName,
+            validation_errors: info.issues,
+        });
+    }
+}

package/dist/GlobalError.js

@@ -2,7 +2,11 @@ export default class GlobalError extends Error {
     context = { message: "" };
     constructor(msg) {
         super(msg);
-        Object.setPrototypeOf(this, GlobalError.prototype);
+        // Standard Error-subclass pattern: pin to new.target's prototype (the
+        // class actually being constructed), not GlobalError's own — otherwise
+        // this clobbers a subclass's correct prototype and `instanceof Subclass`
+        // silently fails for any subclass that doesn't re-pin itself (#736).
+        Object.setPrototypeOf(this, new.target.prototype);
         this.context.message = msg;
     }
     setCode(code) {

package/dist/index.d.ts

@@ -6,30 +6,30 @@
  * published as a back-compat alias — existing imports keep working unchanged —
  * but new code should import from `@blokjs/core`.
  */
-import BlokError, { type BlokErrorOpts, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, isNonRetryableValidationError, type NodeErrorPayload, WORKFLOW_INPUT_VALIDATION } from "./BlokError.js";
+import BlokError, { type BlokErrorOpts, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, isNonRetryableValidationError, type NodeErrorPayload, WORKFLOW_INPUT_VALIDATION, WorkflowInputValidationError, type WorkflowInputValidationInfo, type WorkflowInputValidationIssue } from "./BlokError.js";
 import GlobalError from "./GlobalError.js";
 import GlobalLogger from "./GlobalLogger.js";
 import { Metrics, type MetricsType } from "./Metrics.js";
 import NodeBase from "./NodeBase.js";
 import Trigger from "./Trigger.js";
-import ConfigContext from "./types/ConfigContext.js";
+import type ConfigContext from "./types/ConfigContext.js";
 import type ConnectionContext from "./types/ConnectionContext.js";
-import Context from "./types/Context.js";
-import EnvContext from "./types/EnvContext.js";
-import ErrorContext from "./types/ErrorContext.js";
-import FunctionContext from "./types/FunctionContext.js";
-import LoggerContext from "./types/LoggerContext.js";
-import NodeConfigContext from "./types/NodeConfigContext.js";
-import RequestContext from "./types/RequestContext.js";
+import type Context from "./types/Context.js";
+import type EnvContext from "./types/EnvContext.js";
+import type ErrorContext from "./types/ErrorContext.js";
+import type FunctionContext from "./types/FunctionContext.js";
+import type LoggerContext from "./types/LoggerContext.js";
+import type NodeConfigContext from "./types/NodeConfigContext.js";
+import type RequestContext from "./types/RequestContext.js";
 import { RESPOND_BRAND, type RespondEnvelope, isRespondEnvelope } from "./types/RespondEnvelope.js";
-import ResponseContext from "./types/ResponseContext.js";
-import StateContext from "./types/StateContext.js";
-import Step from "./types/Step.js";
+import type ResponseContext from "./types/ResponseContext.js";
+import type StateContext from "./types/StateContext.js";
+import type Step from "./types/Step.js";
 import type StreamContext from "./types/StreamContext.js";
-import VarsContext from "./types/VarsContext.js";
+import type VarsContext from "./types/VarsContext.js";
 import mapper from "./utils/Mapper.js";
 import { MapperResolutionError } from "./utils/MapperResolutionError.js";
 import MemoryUsage from "./utils/MemoryUsage.js";
 import { NamedMissingStateError } from "./utils/NamedMissingStateError.js";
-import { type StructuralRef, lowerRefs } from "./utils/lowerRefs.js";
-export { NodeBase, Context, RequestContext, ResponseContext, RESPOND_BRAND, type RespondEnvelope, isRespondEnvelope, EnvContext, ErrorContext, LoggerContext, ConfigContext, type ConnectionContext, type StreamContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, Metrics, MemoryUsage, type MetricsType, mapper, MapperResolutionError, NamedMissingStateError, lowerRefs, type StructuralRef, };
+import { type StructuralRef, type StructuralTpl, isStructuralRef, isStructuralTpl, lowerRefs } from "./utils/lowerRefs.js";
+export { NodeBase, type Context, type RequestContext, type ResponseContext, RESPOND_BRAND, type RespondEnvelope, isRespondEnvelope, type EnvContext, type ErrorContext, type LoggerContext, type ConfigContext, type ConnectionContext, type StreamContext, Trigger, type NodeConfigContext, type FunctionContext, type StateContext, type VarsContext, type Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, WorkflowInputValidationError, type WorkflowInputValidationInfo, type WorkflowInputValidationIssue, Metrics, MemoryUsage, type MetricsType, mapper, MapperResolutionError, NamedMissingStateError, lowerRefs, isStructuralRef, isStructuralTpl, type StructuralRef, type StructuralTpl, };

package/dist/index.js

@@ -6,7 +6,7 @@
  * published as a back-compat alias — existing imports keep working unchanged —
  * but new code should import from `@blokjs/core`.
  */
-import BlokError, { DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, } from "./BlokError.js";
+import BlokError, { DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, WorkflowInputValidationError, } from "./BlokError.js";
 import GlobalError from "./GlobalError.js";
 import GlobalLogger from "./GlobalLogger.js";
 import { Metrics } from "./Metrics.js";
@@ -17,5 +17,9 @@ import mapper from "./utils/Mapper.js";
 import { MapperResolutionError } from "./utils/MapperResolutionError.js";
 import MemoryUsage from "./utils/MemoryUsage.js";
 import { NamedMissingStateError } from "./utils/NamedMissingStateError.js";
-import { lowerRefs } from "./utils/lowerRefs.js";
-export { NodeBase, RESPOND_BRAND, isRespondEnvelope, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, Metrics, MemoryUsage, mapper, MapperResolutionError, NamedMissingStateError, lowerRefs, };
+import { isStructuralRef, isStructuralTpl, lowerRefs } from "./utils/lowerRefs.js";
+export { NodeBase, RESPOND_BRAND, isRespondEnvelope, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, isNonRetryableValidationError, WORKFLOW_INPUT_VALIDATION, WorkflowInputValidationError, Metrics, MemoryUsage, mapper, MapperResolutionError, NamedMissingStateError, lowerRefs, 
+// The lowering pass's OWN predicates — exported so the normalizer's
+// post-lowering total invariant (#707) tests the identical rule instead of
+// a second hand-written copy that could drift from what `lowerRefs` lowers.
+isStructuralRef, isStructuralTpl, };

package/dist/utils/lowerRefs.d.ts

@@ -14,7 +14,12 @@
  * BEFORE the Mapper, and compiles every structural `{$ref}` into EXACTLY the
  * wire string today's engine already resolves. The Mapper stays untouched.
  *
- * Scope: the STEP-INPUTS, TRIGGER-ROOT, and TPL positions.
+ * Scope: the STEP-INPUTS, TRIGGER-ROOT, and TPL positions — plus, since #707,
+ * the three RESOLVED-KEY positions (step `idempotencyKey`, trigger
+ * `concurrencyKey`, trigger `debounce.key`), which the normalizer feeds through
+ * this same encoder. The caller picks the positions; this pass is unaware of
+ * them, which is why control positions (`branch.when`, `forEach.in`,
+ * `switch.on`) are simply never handed to it.
  *   - step input value: `"js/ctx.state.<root>" + path`
  *   - `path` mapping: string segment → `.seg`, numeric → `[n]`,
  *     empty `path: []` (whole-output ref) → `"js/ctx.state.<root>"`.
@@ -36,6 +41,25 @@ export interface StructuralRef {
         path?: (string | number)[];
     };
 }
+/**
+ * Is `value` the reserved `{$ref}` sentinel — a single-key object whose only
+ * key is `$ref` and whose `$ref.step` is a string?
+ *
+ * The single-key + string-step guard is what makes `$ref` safe to reserve:
+ * a step-inputs object that legitimately carries unrelated data (even data
+ * with the literal keys `step`/`path`) is NOT a ref and passes through
+ * untouched. ADR 0001 confirmed no current workflow uses `$ref` as user data.
+ */
+export declare function isStructuralRef(value: object): value is StructuralRef;
+/**
+ * The structural template sentinel (#425) — a single-key `{$tpl: [...]}` whose
+ * segments alternate raw strings and `{$ref}` nodes (plus the occasional literal
+ * non-string interpolation). Mirrors `tpl\`...\`` in `core/runner/src/stepBuilder.ts`.
+ */
+export interface StructuralTpl {
+    $tpl: unknown[];
+}
+export declare function isStructuralTpl(value: object): value is StructuralTpl;
 /**
  * Recursively lower every structural `{$ref}` inside `value` to its wire
  * string. Pure — returns a NEW value, never mutates the input. Plain

package/dist/utils/lowerRefs.js

@@ -14,7 +14,12 @@
  * BEFORE the Mapper, and compiles every structural `{$ref}` into EXACTLY the
  * wire string today's engine already resolves. The Mapper stays untouched.
  *
- * Scope: the STEP-INPUTS, TRIGGER-ROOT, and TPL positions.
+ * Scope: the STEP-INPUTS, TRIGGER-ROOT, and TPL positions — plus, since #707,
+ * the three RESOLVED-KEY positions (step `idempotencyKey`, trigger
+ * `concurrencyKey`, trigger `debounce.key`), which the normalizer feeds through
+ * this same encoder. The caller picks the positions; this pass is unaware of
+ * them, which is why control positions (`branch.when`, `forEach.in`,
+ * `switch.on`) are simply never handed to it.
  *   - step input value: `"js/ctx.state.<root>" + path`
  *   - `path` mapping: string segment → `.seg`, numeric → `[n]`,
  *     empty `path: []` (whole-output ref) → `"js/ctx.state.<root>"`.
@@ -38,7 +43,7 @@
  * with the literal keys `step`/`path`) is NOT a ref and passes through
  * untouched. ADR 0001 confirmed no current workflow uses `$ref` as user data.
  */
-function isStructuralRef(value) {
+export function isStructuralRef(value) {
     const keys = Object.keys(value);
     if (keys.length !== 1 || keys[0] !== "$ref")
         return false;
@@ -126,7 +131,7 @@ function refExpr(ref) {
 function lowerRef(ref) {
     return `js/${refExpr(ref)}`;
 }
-function isStructuralTpl(value) {
+export function isStructuralTpl(value) {
     const keys = Object.keys(value);
     return keys.length === 1 && keys[0] === "$tpl" && Array.isArray(value.$tpl);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/shared",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"files": ["dist"],
 	"description": "Shared class, interfaces and types",
 	"type": "module",