@codemation/core-nodes 1.0.2 → 1.1.0

package/src/http/HttpRequestExecutor.ts

@@ -0,0 +1,150 @@
+import type { Item } from "@codemation/core";
+import type { HttpRequestResult, HttpRequestSpec } from "./httpRequest.types";
+import type { HttpBodyBuilder } from "./HttpBodyBuilder";
+import type { HttpUrlBuilder } from "./HttpUrlBuilder";
+
+/**
+ * Executes a single HTTP request described by {@link HttpRequestSpec}.
+ *
+ * - Credential sessions provide header/query deltas via `applyToRequest`.
+ * - Body encoding is delegated to {@link HttpBodyBuilder}.
+ * - URL query merging is delegated to {@link HttpUrlBuilder}.
+ * - Binary response bodies: when `download.mode` triggers binary attach, the
+ *   `bodyBinaryName` field is set in the result but the body is NOT read here.
+ *   Callers that need binary attachment should use `buildRequest` to get the
+ *   resolved URL + init and make the fetch + binary attach themselves.
+ *
+ * Collaborators (`fetch`, body builder, url builder) are injected so callers
+ * own construction at composition roots and tests can supply deterministic stubs.
+ */
+export class HttpRequestExecutor {
+  constructor(
+    private readonly fetchFn: typeof globalThis.fetch,
+    private readonly bodyBuilder: HttpBodyBuilder,
+    private readonly urlBuilder: HttpUrlBuilder,
+  ) {}
+
+  /**
+   * Builds the fetch init (headers, query, body) from the spec + credential delta,
+   * returning both the resolved URL and the RequestInit so callers can make the
+   * actual fetch call themselves (useful for streaming / binary attach).
+   */
+  async buildRequest(spec: HttpRequestSpec, item: Item): Promise<Readonly<{ url: string; init: RequestInit }>> {
+    const credentialDelta = spec.credential?.applyToRequest(spec) ?? {};
+
+    const mergedHeaders: Record<string, string> = {
+      ...(spec.headers ?? {}),
+      ...(credentialDelta.headers ?? {}),
+    };
+
+    const mergedQuery: Record<string, string | string[]> = {
+      ...(spec.query ?? {}),
+      ...(credentialDelta.query ?? {}),
+    };
+
+    const encodedBody = await this.bodyBuilder.build(spec.body, item, spec.ctx);
+
+    // Only set Content-Type from the encoded body when it is non-empty
+    // (empty string = FormData will set it automatically).
+    if (encodedBody && encodedBody.contentType) {
+      mergedHeaders["content-type"] = encodedBody.contentType;
+    }
+
+    const resolvedUrl = this.urlBuilder.build(spec.url, mergedQuery);
+
+    const init: RequestInit = {
+      method: spec.method,
+      headers: mergedHeaders,
+      ...(encodedBody ? { body: encodedBody.body } : {}),
+    };
+
+    return { url: resolvedUrl, init };
+  }
+
+  /**
+   * Executes an HTTP request and returns parsed result.
+   * For binary downloads (when `shouldAttachBody` is true), the body is NOT consumed
+   * and callers must call `ctx.binary.attach` directly using the resolved URL + init
+   * (available via `buildRequest`).
+   */
+  async execute(spec: HttpRequestSpec, item: Item): Promise<HttpRequestResult> {
+    const { url: resolvedUrl, init } = await this.buildRequest(spec, item);
+
+    const response = await this.fetchFn(resolvedUrl, init);
+
+    const responseHeaders = this.readHeaders(response.headers);
+    const mimeType = this.resolveMimeType(responseHeaders);
+
+    const downloadMode = spec.download?.mode ?? "auto";
+    const binaryName = spec.download?.binaryName ?? "body";
+    const shouldDownload = this.shouldAttachBody(downloadMode, mimeType);
+
+    const isJson = this.isJsonMimeType(mimeType);
+
+    let json: unknown | undefined;
+    let text: string | undefined;
+    let bodyBinaryName: string | undefined;
+
+    if (shouldDownload) {
+      // Signal to caller that binary attachment is needed.
+      bodyBinaryName = binaryName;
+      // Do NOT read the body here — the caller must handle binary attach separately.
+    } else if (isJson) {
+      try {
+        json = await response.json();
+      } catch {
+        text = await response.text();
+      }
+    } else {
+      text = await response.text();
+    }
+
+    return {
+      url: resolvedUrl,
+      method: spec.method.toUpperCase(),
+      status: response.status,
+      ok: response.ok,
+      statusText: response.statusText,
+      mimeType,
+      headers: responseHeaders,
+      ...(json !== undefined ? { json } : {}),
+      ...(text !== undefined ? { text } : {}),
+      ...(bodyBinaryName !== undefined ? { bodyBinaryName } : {}),
+    };
+  }
+
+  private readHeaders(headers: Headers): Readonly<Record<string, string>> {
+    const values: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      values[key] = value;
+    });
+    return values;
+  }
+
+  private resolveMimeType(headers: Readonly<Record<string, string>>): string {
+    const contentType = headers["content-type"];
+    if (!contentType) {
+      return "application/octet-stream";
+    }
+    return contentType.split(";")[0]?.trim() || "application/octet-stream";
+  }
+
+  private isJsonMimeType(mimeType: string): boolean {
+    return mimeType === "application/json" || mimeType.endsWith("+json");
+  }
+
+  private shouldAttachBody(mode: "auto" | "always" | "never", mimeType: string): boolean {
+    if (mode === "always") {
+      return true;
+    }
+    if (mode === "never") {
+      return false;
+    }
+    return (
+      mimeType.startsWith("image/") ||
+      mimeType.startsWith("audio/") ||
+      mimeType.startsWith("video/") ||
+      mimeType === "application/pdf"
+    );
+  }
+}

package/src/http/HttpUrlBuilder.ts

@@ -0,0 +1,22 @@
+/**
+ * Merges query parameters into a base URL.
+ * Handles both scalar and array values, and preserves any existing params.
+ */
+export class HttpUrlBuilder {
+  build(baseUrl: string, query?: Readonly<Record<string, string | string[]>>): string {
+    if (!query || Object.keys(query).length === 0) {
+      return baseUrl;
+    }
+    const parsed = new URL(baseUrl);
+    for (const [key, value] of Object.entries(query)) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          parsed.searchParams.append(key, entry);
+        }
+      } else {
+        parsed.searchParams.append(key, value);
+      }
+    }
+    return parsed.toString();
+  }
+}

package/src/http/httpRequest.types.ts

@@ -0,0 +1,69 @@
+import type { NodeExecutionContext } from "@codemation/core";
+import type { RunnableNodeConfig } from "@codemation/core";
+
+/**
+ * Binary reference key into `item.binary`.
+ */
+export type BinaryRef = string;
+
+/**
+ * Discriminated union for the HTTP request body.
+ */
+export type HttpBodySpec =
+  | Readonly<{ kind: "none" }>
+  | Readonly<{ kind: "json"; data: unknown }>
+  | Readonly<{ kind: "form"; data: Readonly<Record<string, string>> }>
+  | Readonly<{
+      kind: "multipart";
+      fields: Readonly<Record<string, string>>;
+      binaries?: Readonly<Record<string, BinaryRef>>;
+    }>;
+
+/**
+ * Session interface that credential types implement.
+ * Returns header/query deltas so the executor can merge them without
+ * mutating the immutable HttpRequestSpec.
+ */
+export interface CredentialSession {
+  applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
+}
+
+/**
+ * Mutations the credential session wants to apply to the outgoing request.
+ */
+export type HttpCredentialDelta = Readonly<{
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string>>;
+}>;
+
+/**
+ * Full specification of one HTTP request. All URLs are fully resolved before
+ * being passed here (template substitution already applied by the caller).
+ */
+export type HttpRequestSpec = Readonly<{
+  url: string;
+  method: string;
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string | string[]>>;
+  body?: HttpBodySpec;
+  credential?: CredentialSession;
+  download?: Readonly<{ mode: "auto" | "always" | "never"; binaryName: string }>;
+  /** Execution context — needed for binary attach. */
+  ctx: NodeExecutionContext<RunnableNodeConfig<unknown, unknown>>;
+}>;
+
+/**
+ * Result of executing an HTTP request.
+ */
+export type HttpRequestResult = Readonly<{
+  url: string;
+  method: string;
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+  bodyBinaryName?: string;
+}>;

package/src/index.ts

@@ -1,22 +1,30 @@
 export * from "./canvasIconName";
+export * from "./credentials/index";
+export * from "./http/httpRequest.types";
+export * from "./authoring/defineRestNode.types";
 export * from "./chatModels/OpenAIChatModelFactory";
 export * from "./chatModels/OpenAiStrictJsonSchemaFactory";
 export * from "./chatModels/OpenAiCredentialSession";
 export * from "./chatModels/openAiChatModelConfig";
 export * from "./chatModels/OpenAiChatModelPresetsFactory";
 export * from "./nodes/aiAgent";
+export * from "./nodes/assertion";
 export * from "./nodes/CallbackNodeFactory";
 export * from "./nodes/httpRequest";
 export * from "./nodes/aggregate";
 export * from "./nodes/filter";
 export * from "./nodes/if";
+export * from "./nodes/isTestRun";
 export * from "./nodes/switch";
 export * from "./nodes/split";
+export * from "./nodes/CronTriggerFactory";
+export * from "./nodes/CronTriggerNode";
 export * from "./nodes/ManualTriggerFactory";
 export * from "./nodes/mapData";
 export * from "./nodes/merge";
 export * from "./nodes/noOp";
 export * from "./nodes/subWorkflow";
+export * from "./nodes/testTrigger";
 export * from "./nodes/wait";
 export * from "./nodes/webhookRespondNowAndContinueError";
 export * from "./nodes/webhookRespondNowError";
@@ -30,3 +38,4 @@ export * from "./nodes/ConnectionCredentialNode";
 export * from "./nodes/ConnectionCredentialNodeConfig";
 export * from "./nodes/ConnectionCredentialNodeConfigFactory";
 export * from "./nodes/ConnectionCredentialExecutionContextFactory";
+export * from "./nodes/collections";

package/src/nodes/AssertionNode.ts

@@ -0,0 +1,42 @@
+import type { AssertionResult, RunnableNode, RunnableNodeExecuteArgs } from "@codemation/core";
+import { node } from "@codemation/core";
+
+import { Assertion } from "./assertion";
+
+/**
+ * Runs the author's `assertions` callback for each input item and emits one workflow `Item` per
+ * returned {@link AssertionResult} on `main`. Persistence is handled by a host-side subscriber
+ * to `nodeCompleted` events that filters on `config.emitsAssertions === true`; this node does
+ * not write to any store on its own.
+ *
+ * If the author callback throws, we emit a single synthetic AssertionResult with `errored: true`
+ * and `score: 0`. Without this catch the whole node would fail and no assertion row would be
+ * persisted — making the rollup blind to "the assertion code itself is broken." The synthetic
+ * row keeps `failedAssertionsByRunId` consistent and gives the UI something to surface.
+ */
+@node({ packageName: "@codemation/core-nodes" })
+export class AssertionNode implements RunnableNode<Assertion<any>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(args: RunnableNodeExecuteArgs<Assertion<any>>): Promise<unknown> {
+    const ctx = args.ctx;
+    const config = ctx.config;
+    try {
+      const results: ReadonlyArray<AssertionResult> = await config.assertions(args.item, ctx);
+      // Engine "array → fan-out on main, each element is item.json" — returning the plain results
+      // makes downstream `item.json` exactly an AssertionResult. Wrapping in `{ json: result }`
+      // would double-wrap (engine would see `Item`-shaped values but treat them as JSON values).
+      return [...results];
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const erroredResult: AssertionResult = {
+        name: config.name ?? "assertion",
+        score: 0,
+        errored: true,
+        message,
+      };
+      return [erroredResult];
+    }
+  }
+}

package/src/nodes/CronTriggerFactory.ts

@@ -0,0 +1,45 @@
+import type { TriggerNodeConfig, TypeToken } from "@codemation/core";
+
+import { Cron } from "croner";
+import type { CronCallback } from "croner";
+
+import { CronTriggerNode } from "./CronTriggerNode";
+
+export type CronTickJson = { firedAt: string; scheduledFor: string };
+
+/**
+ * Schedules a workflow on a standard cron expression.
+ *
+ * Each tick emits one item: `{ firedAt: string, scheduledFor: string }` — both ISO-8601 timestamps.
+ * `firedAt` is the wall-clock moment the callback ran; `scheduledFor` is the cron-computed
+ * firing instant (these differ when the job was delayed).
+ *
+ * Timezone defaults to UTC when omitted — cron without an explicit TZ is a DST footgun.
+ */
+export class CronTrigger implements TriggerNodeConfig<CronTickJson> {
+  readonly kind = "trigger" as const;
+  readonly type: TypeToken<unknown> = CronTriggerNode;
+  readonly icon = "lucide:clock" as const;
+  readonly id?: string;
+
+  constructor(
+    public readonly name: string,
+    private readonly args: Readonly<{ schedule: string; timezone?: string }>,
+    id?: string,
+  ) {
+    new Cron(args.schedule, { paused: true, timezone: args.timezone });
+    this.id = id;
+  }
+
+  get schedule(): string {
+    return this.args.schedule;
+  }
+
+  get timezone(): string | undefined {
+    return this.args.timezone;
+  }
+
+  createJob(callback: CronCallback): Cron {
+    return new Cron(this.args.schedule, { timezone: this.args.timezone, protect: true }, callback);
+  }
+}

package/src/nodes/CronTriggerNode.ts

@@ -0,0 +1,40 @@
+import type {
+  Items,
+  NodeExecutionContext,
+  NodeOutputs,
+  TestableTriggerNode,
+  TriggerSetupContext,
+  TriggerTestItemsContext,
+} from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import { CronTrigger } from "./CronTriggerFactory";
+
+@node({ packageName: "@codemation/core-nodes" })
+export class CronTriggerNode implements TestableTriggerNode<CronTrigger> {
+  readonly kind = "trigger" as const;
+  readonly outputPorts = ["main"] as const;
+
+  async setup(ctx: TriggerSetupContext<CronTrigger>): Promise<undefined> {
+    const job = ctx.config.createJob(async (self) => {
+      const scheduledFor = self.currentRun()?.toISOString() ?? ctx.now().toISOString();
+      await ctx.emit([{ json: { firedAt: ctx.now().toISOString(), scheduledFor } }]);
+    });
+    ctx.registerCleanup({
+      stop: () => {
+        job.stop();
+      },
+    });
+    return undefined;
+  }
+
+  async execute(items: Items, _ctx: NodeExecutionContext<CronTrigger>): Promise<NodeOutputs> {
+    return { main: items };
+  }
+
+  async getTestItems(ctx: TriggerTestItemsContext<CronTrigger>): Promise<Items> {
+    const nowIso = ctx.now().toISOString();
+    return [{ json: { firedAt: nowIso, scheduledFor: nowIso } }];
+  }
+}

package/src/nodes/HttpRequestNodeFactory.ts

@@ -1,7 +1,10 @@
 import type { Item, NodeExecutionContext, RunnableNode, RunnableNodeExecuteArgs } from "@codemation/core";
 
 import { node } from "@codemation/core";
-
+import type { CredentialSession, HttpRequestSpec } from "../http/httpRequest.types";
+import { HttpRequestExecutor } from "../http/HttpRequestExecutor";
+import { HttpBodyBuilder } from "../http/HttpBodyBuilder";
+import { HttpUrlBuilder } from "../http/HttpUrlBuilder";
 import type { HttpRequestDownloadMode } from "./httpRequest";
 import { HttpRequest } from "./httpRequest";
 
@@ -16,44 +19,113 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
 
   private async executeItem(item: Item, ctx: NodeExecutionContext<HttpRequest<any, any>>): Promise<Item> {
     const url = this.resolveUrl(item, ctx);
-    const response = await fetch(url, {
+    const credential = await this.resolveCredential(ctx);
+
+    const spec: HttpRequestSpec = {
+      url,
       method: ctx.config.method,
-    });
+      headers: ctx.config.args.headers,
+      query: ctx.config.args.query,
+      body: ctx.config.args.body,
+      credential,
+      download: {
+        mode: ctx.config.downloadMode,
+        binaryName: ctx.config.binaryName,
+      },
+      ctx: ctx as unknown as HttpRequestSpec["ctx"],
+    };
+
+    // Build the request (headers, body encoding, URL query merge) once,
+    // then make a SINGLE fetch call and decide what to do with the response.
+    // This avoids a double-fetch regression for auto-mode binary responses.
+    const executor = new HttpRequestExecutor(globalThis.fetch, new HttpBodyBuilder(), new HttpUrlBuilder());
+    const { url: resolvedUrl, init } = await executor.buildRequest(spec, item);
+
+    const response = await globalThis.fetch(resolvedUrl, init);
+
     const headers = this.readHeaders(response.headers);
     const mimeType = this.resolveMimeType(headers);
-    const bodyBinaryName = ctx.config.binaryName;
-    const shouldAttachBody = this.shouldAttachBody(ctx.config.downloadMode, mimeType);
+    const binaryName = ctx.config.binaryName;
+    const shouldAttach = this.shouldAttachBody(ctx.config.downloadMode, mimeType);
+
+    if (shouldAttach) {
+      const outputJson: Readonly<Record<string, unknown>> = {
+        url: resolvedUrl,
+        method: ctx.config.method,
+        ok: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+        mimeType,
+        headers,
+        bodyBinaryName: binaryName,
+      };
+
+      const attachment = await ctx.binary.attach({
+        name: binaryName,
+        body: response.body
+          ? (response.body as unknown as Parameters<typeof ctx.binary.attach>[0]["body"])
+          : new Uint8Array(await response.arrayBuffer()),
+        mimeType,
+        filename: this.resolveFilename(resolvedUrl, headers),
+      });
+
+      let outputItem: Item = { json: outputJson };
+      outputItem = ctx.binary.withAttachment(outputItem, binaryName, attachment);
+      return outputItem;
+    }
+
+    // Non-binary path: parse JSON or read text.
+    const isJson = this.isJsonMimeType(mimeType);
+    let json: unknown | undefined;
+    let text: string | undefined;
+
+    if (isJson) {
+      try {
+        json = await response.json();
+      } catch {
+        text = await response.text();
+      }
+    } else {
+      text = await response.text();
+    }
+
     const outputJson: Readonly<Record<string, unknown>> = {
-      url,
+      url: resolvedUrl,
       method: ctx.config.method,
       ok: response.ok,
       status: response.status,
       statusText: response.statusText,
       mimeType,
       headers,
-      ...(shouldAttachBody ? { bodyBinaryName } : {}),
+      ...(json !== undefined ? { json } : {}),
+      ...(text !== undefined ? { text } : {}),
     };
 
-    let outputItem: Item = {
-      json: outputJson,
-    };
-    if (!shouldAttachBody) {
-      return outputItem;
-    }
+    return { json: outputJson };
+  }
 
-    const attachment = await ctx.binary.attach({
-      name: bodyBinaryName,
-      body: response.body
-        ? (response.body as unknown as Parameters<typeof ctx.binary.attach>[0]["body"])
-        : new Uint8Array(await response.arrayBuffer()),
-      mimeType,
-      filename: this.resolveFilename(url, headers),
-    });
-    outputItem = ctx.binary.withAttachment(outputItem, bodyBinaryName, attachment);
-    return outputItem;
+  private async resolveCredential(
+    ctx: NodeExecutionContext<HttpRequest<any, any>>,
+  ): Promise<CredentialSession | undefined> {
+    const slotKey = ctx.config.args.credentialSlot;
+    if (!slotKey) {
+      return undefined;
+    }
+    try {
+      return await ctx.getCredential<CredentialSession>(slotKey);
+    } catch {
+      // Credential slot configured but not bound — treat as no credential.
+      return undefined;
+    }
   }
 
   private resolveUrl(item: Item, ctx: NodeExecutionContext<HttpRequest<any, any>>): string {
+    // Literal URL in args takes precedence over the legacy urlField approach.
+    const literalUrl = ctx.config.args.url;
+    if (literalUrl && literalUrl.trim().length > 0) {
+      return literalUrl.trim();
+    }
+
     const json = this.asRecord(item.json);
     const candidate = json[ctx.config.urlField];
     if (typeof candidate !== "string" || candidate.trim() === "") {
@@ -85,6 +157,10 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
     return contentType.split(";")[0]?.trim() || "application/octet-stream";
   }
 
+  private isJsonMimeType(mimeType: string): boolean {
+    return mimeType === "application/json" || mimeType.endsWith("+json");
+  }
+
   private shouldAttachBody(mode: HttpRequestDownloadMode, mimeType: string): boolean {
     if (mode === "always") {
       return true;

package/src/nodes/IsTestRunNode.ts

@@ -0,0 +1,25 @@
+import type { RunnableNode, RunnableNodeExecuteArgs } from "@codemation/core";
+import { emitPorts, node } from "@codemation/core";
+
+import { IsTestRun } from "./isTestRun";
+
+/**
+ * Routes each item to the `true` port if `ctx.testContext` is set (the run was started by the
+ * TestSuiteOrchestrator), else to `false`. Lets workflow authors guard real side-effects:
+ *
+ *   GmailTrigger / TestTrigger → ClassifyAgent → IsTestRun
+ *                                                 ├── true → AssertionNode
+ *                                                 └── false → SendReply
+ */
+@node({ packageName: "@codemation/core-nodes" })
+export class IsTestRunNode implements RunnableNode<IsTestRun<unknown>> {
+  kind = "node" as const;
+
+  execute(args: RunnableNodeExecuteArgs<IsTestRun<unknown>>): unknown {
+    const isTest = args.ctx.testContext !== undefined;
+    return emitPorts({
+      true: isTest ? [args.item] : [],
+      false: isTest ? [] : [args.item],
+    });
+  }
+}

package/src/nodes/TestTriggerNode.ts

@@ -0,0 +1,33 @@
+import type {
+  Items,
+  NodeExecutionContext,
+  NodeOutputs,
+  TestTriggerNodeConfig,
+  TriggerNode,
+  TriggerSetupContext,
+} from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+/**
+ * Author-defined test-fixture trigger. Live activation skips this trigger (filtered by
+ * `triggerKind === "test"` in `TriggerRuntimeService`); the `TestSuiteOrchestrator` drives its
+ * `generateItems` callback during a TestSuiteRun and dispatches one workflow run per yielded item.
+ *
+ * `setup` is intentionally a no-op for symmetry with other trigger nodes — the real work happens
+ * in the orchestrator. `execute` is a passthrough so items provided to `engine.runWorkflow(...)`
+ * (one per case) flow downstream unchanged on `main`.
+ */
+@node({ packageName: "@codemation/core-nodes" })
+export class TestTriggerNode implements TriggerNode<TestTriggerNodeConfig<any>> {
+  kind = "trigger" as const;
+  outputPorts = ["main"] as const;
+
+  async setup(_ctx: TriggerSetupContext<TestTriggerNodeConfig<any>>): Promise<undefined> {
+    return undefined;
+  }
+
+  async execute(items: Items, _ctx: NodeExecutionContext<TestTriggerNodeConfig<any>>): Promise<NodeOutputs> {
+    return { main: items };
+  }
+}

package/src/nodes/assertion.ts

@@ -0,0 +1,42 @@
+import type { AssertionResult, Item, NodeExecutionContext, RunnableNodeConfig, TypeToken } from "@codemation/core";
+
+import { AssertionNode } from "./AssertionNode";
+
+export interface AssertionOptions<TInputJson> {
+  readonly name?: string;
+  readonly id?: string;
+  readonly icon?: string;
+  /**
+   * Author callback. Returns one or more {@link AssertionResult}s per input item. Each becomes
+   * one emitted output item — useful for per-row reporting in the Tests tab. Return `[]` to
+   * emit nothing for this case (rare; usually you want at least a "no-op" pass).
+   */
+  assertions(
+    item: Item<TInputJson>,
+    ctx: NodeExecutionContext<Assertion<TInputJson>>,
+  ): Promise<ReadonlyArray<AssertionResult>> | ReadonlyArray<AssertionResult>;
+}
+
+/**
+ * Generic assertion node — the "callback" form. For declarative shorthands (StringEquals,
+ * JudgeByAgent) compose this with helpers added in later phases. Sets `emitsAssertions: true`
+ * so host-side persisters know to record its outputs as `TestAssertion` rows.
+ */
+export class Assertion<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, AssertionResult> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = AssertionNode;
+  readonly icon: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly emitsAssertions = true as const;
+  readonly assertions: AssertionOptions<TInputJson>["assertions"];
+
+  constructor(options: AssertionOptions<TInputJson>) {
+    this.name = options.name ?? "Assertion";
+    this.id = options.id;
+    this.icon = options.icon ?? "lucide:check-circle";
+    this.assertions = options.assertions;
+  }
+}
+
+export { AssertionNode } from "./AssertionNode";