@codemation/core-nodes 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { AssistantModelMessage, ModelMessage, ToolModelMessage } from "ai";
+import { Cron, CronCallback } from "croner";
 import { ReadableStream } from "node:stream/web";
-import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
 import { ZodType, input, output, z } from "zod";
+import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
 
 //#region src/canvasIconName.d.ts
-
 /**
  * Canvas / agent presentation:
  * - Lucide: `lucide:<kebab-name>` or legacy kebab name
@@ -14,170 +14,223 @@ import { ZodType, input, output, z } from "zod";
  */
 type CanvasIconName = string;
 //#endregion
-//#region ../core/src/contracts/emitPorts.d.ts
-declare const EMIT_PORTS_BRAND: unique symbol;
-type PortsEmission = Readonly<{
-  readonly [EMIT_PORTS_BRAND]: true;
-  readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
-}>;
+//#region ../core/src/contracts/baseTypes.d.ts
+/**
+ * Minimal base types that have no dependencies on other contracts.
+ * Used by credentialTypes, workflowTypes, and other contract layers
+ * to avoid circular dependencies.
+ */
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type NodeConnectionName = string;
 //#endregion
-//#region ../core/src/contracts/itemExpr.d.ts
-declare const ITEM_EXPR_BRAND: unique symbol;
-type ItemExprResolvedContext = Readonly<{
-  runId: RunId;
-  workflowId: WorkflowId;
-  nodeId: NodeId;
-  activationId: NodeActivationId;
-  data: RunDataSnapshot;
+//#region ../core/src/contracts/credentialTypes.d.ts
+type CredentialTypeId = string;
+type CredentialInstanceId = string;
+type CredentialMaterialSourceKind = "db" | "env" | "code";
+type CredentialSetupStatus = "draft" | "ready";
+type CredentialHealthStatus = "unknown" | "healthy" | "failing";
+type CredentialFieldSchema = Readonly<{
+  key: string;
+  label: string;
+  type: "string" | "password" | "textarea" | "json" | "boolean";
+  required?: true;
+  order?: number;
+  /**
+   * Where this field appears in the credential dialog. Use `"advanced"` for optional or
+   * power-user fields; they render inside a collapsible section (see `CredentialTypeDefinition.advancedSection`).
+   * Defaults to `"default"` when omitted.
+   */
+  visibility?: "default" | "advanced";
+  placeholder?: string;
+  helpText?: string;
+  /** When set, host resolves this field from process.env at runtime; env wins over stored values. */
+  envVarName?: string;
+  /**
+   * When set, the dialog shows a copy action for this exact string (e.g. a static OAuth redirect URI
+   * pattern or documentation URL). Do not use for secret values.
+   */
+  copyValue?: string;
+  /** Accessible label for the copy control (default: Copy). */
+  copyButtonLabel?: string;
+}>;
+type CredentialRequirement = Readonly<{
+  slotKey: string;
+  label: string;
+  acceptedTypes: ReadonlyArray<CredentialTypeId>;
+  optional?: true;
+  helpText?: string;
+  helpUrl?: string;
+}>;
+type CredentialHealth = Readonly<{
+  status: CredentialHealthStatus;
+  message?: string;
+  testedAt?: string;
+  expiresAt?: string;
+  details?: Readonly<Record<string, unknown>>;
+}>;
+type OAuth2ProviderFromPublicConfig = Readonly<{
+  authorizeUrlFieldKey: string;
+  tokenUrlFieldKey: string;
+  userInfoUrlFieldKey?: string;
+}>;
+type CredentialOAuth2ScopesFromPublicConfig = Readonly<{
+  presetFieldKey: string;
+  presetScopes: Readonly<Record<string, ReadonlyArray<string>>>;
+  customPresetKey?: string;
+  customScopesFieldKey?: string;
+}>;
+type CredentialOAuth2AuthDefinition = Readonly<{
+  kind: "oauth2";
+  providerId: string;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+} | {
+  kind: "oauth2";
+  providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+} | {
+  kind: "oauth2";
+  /**
+   * Free-form provider identifier for telemetry, DB rows, and Better Auth provider naming.
+   * Not used for any registry lookup — URLs come from {@link authorizeUrl} / {@link tokenUrl}.
+   */
+  providerId: string;
+  /**
+   * Authorization endpoint. May contain `{publicFieldKey}` placeholders that the runtime
+   * substitutes from the credential's resolved public config (URL-encoded).
+   * Example: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize`
+   */
+  authorizeUrl: string;
+  /** Token endpoint. Same templating rules as {@link authorizeUrl}. */
+  tokenUrl: string;
+  /** Optional userinfo endpoint. Same templating rules as {@link authorizeUrl}. */
+  userInfoUrl?: string;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+}>;
+type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
+type CredentialAdvancedSectionPresentation = Readonly<{
+  /** Collapsible section title (default: "Advanced"). */
+  title?: string;
+  /** Optional short helper text shown inside the section (above the fields). */
+  description?: string;
+  /** When true, the advanced section starts expanded. Default: false (collapsed). */
+  defaultOpen?: boolean;
+}>;
+type CredentialTypeDefinition = Readonly<{
+  typeId: CredentialTypeId;
+  displayName: string;
+  description?: string;
+  publicFields?: ReadonlyArray<CredentialFieldSchema>;
+  secretFields?: ReadonlyArray<CredentialFieldSchema>;
+  /**
+   * Optional labels for the collapsible block that contains every field with `visibility: "advanced"`.
+   * If omitted, the UI still shows that block with defaults (title "Advanced", collapsed).
+   */
+  advancedSection?: CredentialAdvancedSectionPresentation;
+  supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+  auth?: CredentialAuthDefinition;
 }>;
 /**
- * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
+ * JSON-shaped credential field bag (public config, resolved secret material, etc.).
  */
-type ItemExprContext = ItemExprResolvedContext;
-type ItemExprArgs<TItemJson = unknown> = Readonly<{
-  item: Item<TItemJson>;
-  itemIndex: number;
-  items: Items<TItemJson>;
-  ctx: ItemExprContext;
+type CredentialJsonRecord = Readonly<Record<string, unknown>>;
+/**
+ * Persisted credential instance with typed `publicConfig`.
+ * Hosts may specialize `secretRef` with a stricter union while remaining
+ * assignable here for session/test callbacks.
+ */
+type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instanceId: CredentialInstanceId;
+  typeId: CredentialTypeId;
+  displayName: string;
+  sourceKind: CredentialMaterialSourceKind;
+  publicConfig: TPublicConfig;
+  secretRef: CredentialJsonRecord;
+  tags: ReadonlyArray<string>;
+  setupStatus: CredentialSetupStatus;
+  createdAt: string;
+  updatedAt: string;
 }>;
-type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
-type ItemExpr<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_EXPR_BRAND]: true;
-  readonly fn: ItemExprCallback<T, TItemJson>;
+/**
+ * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
+ * Declare `TPublicConfig` / `TMaterial` on `CredentialType` so implementations are checked
+ * against your credential shapes (similar to `NodeExecutionContext.config` for nodes).
+ */
+type CredentialSessionFactoryArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instance: CredentialInstanceRecord<TPublicConfig>;
+  material: TMaterial;
+  publicConfig: TPublicConfig;
 }>;
-//#endregion
-//#region ../core/src/contracts/params.d.ts
-type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
-type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
-//#endregion
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+type CredentialSessionFactory<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
+type CredentialHealthTester<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<CredentialHealth>;
 /**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ * Full credential type implementation: `definition` (UI/schema), `createSession`, and `test`.
+ * Use this at registration and config boundaries; `CredentialTypeDefinition` is only the schema slice.
  */
-type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
-interface NoneRetryPolicySpec {
-  readonly kind: "none";
-}
-interface FixedRetryPolicySpec {
-  readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly delayMs: number;
-}
-interface ExponentialRetryPolicySpec {
-  readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly initialDelayMs: number;
-  readonly multiplier: number;
-  readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
-  readonly jitter?: boolean;
+type CredentialType<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = Readonly<{
+  definition: CredentialTypeDefinition;
+  createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
+  test: CredentialHealthTester<TPublicConfig, TMaterial>;
+}>;
+/**
+ * Credential type with unspecified generics — used for `CodemationConfig.credentialTypes`, the host registry,
+ * and anywhere a concrete `CredentialType<YourPublic, YourMaterial, YourSession>` is placed in a heterogeneous list.
+ * Using `any` here avoids unsafe `as` casts while keeping typed `satisfies CredentialType<…>` definitions.
+ */
+type AnyCredentialType = CredentialType<any, any, unknown>;
+interface CredentialSessionService {
+  getSession<TSession = unknown>(args: Readonly<{
+    workflowId: WorkflowId;
+    nodeId: NodeId;
+    slotKey: string;
+  }>): Promise<TSession>;
 }
 //#endregion
-//#region ../core/src/contracts/telemetryTypes.d.ts
-type TelemetryAttributePrimitive = string | number | boolean | null;
-interface TelemetryAttributes {
-  readonly [key: string]: TelemetryAttributePrimitive | undefined;
-}
-interface TelemetryMetricRecord {
-  readonly name: string;
-  readonly value: number;
-  readonly unit?: string;
-  readonly attributes?: TelemetryAttributes;
+//#region ../core/src/triggers/polling/PollingTriggerDedupWindow.d.ts
+/**
+ * Merges processed-ID windows for polling triggers, capping the total to avoid unbounded growth.
+ * Plugin code receives an instance of this class via {@link PollingTriggerHandle.dedup}.
+ */
+declare class PollingTriggerDedupWindow {
+  static readonly defaultCapN = 2000;
+  merge(previous: ReadonlyArray<string>, incoming: ReadonlyArray<string>, capN?: number): ReadonlyArray<string>;
 }
-interface TelemetrySpanEventRecord {
-  readonly name: string;
-  readonly occurredAt?: Date;
-  readonly attributes?: TelemetryAttributes;
+//#endregion
+//#region ../core/src/contracts/runTypes.d.ts
+/**
+ * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
+ * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
+ * off the presence of this field. Subworkflow runs inherit it from their parent run.
+ */
+interface RunTestContext {
+  readonly testSuiteRunId: string;
+  readonly testCaseIndex: number;
+  /**
+   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
+   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
+   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
+   * instead of "run_1777755971399_bbb86beac1396".
+   */
+  readonly testCaseLabel?: string;
 }
-interface TelemetryArtifactAttachment {
-  readonly kind: string;
-  readonly contentType: string;
-  readonly previewText?: string;
-  readonly previewJson?: JsonValue;
-  readonly payloadText?: string;
-  readonly payloadJson?: JsonValue;
-  readonly bytes?: number;
-  readonly truncated?: boolean;
-  readonly expiresAt?: Date;
-}
-interface TelemetryArtifactReference {
-  readonly artifactId: string;
-  readonly traceId?: string;
-  readonly spanId?: string;
-}
-interface TelemetrySpanEnd {
-  readonly status?: "ok" | "error";
-  readonly statusMessage?: string;
-  readonly endedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryChildSpanStart {
-  readonly name: string;
-  readonly kind?: "internal" | "client";
-  readonly startedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryScope {
-  readonly traceId?: string;
-  readonly spanId?: string;
-  readonly costTracking?: CostTrackingTelemetry;
-  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
-  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
-  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
-}
-interface TelemetrySpanScope extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  end(args?: TelemetrySpanEnd): Promise<void> | void;
-}
-interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
-  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
-}
-interface ExecutionTelemetry extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  forNode(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
-type CostTrackingComponent = "chat" | "ocr" | "rag";
-interface CostTrackingUsageRecord {
-  readonly component: CostTrackingComponent;
-  readonly provider: string;
-  readonly operation: string;
-  readonly pricingKey: string;
-  readonly usageUnit: string;
-  readonly quantity: number;
-  readonly modelName?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface CostTrackingPriceQuote {
-  readonly currency: string;
-  readonly currencyScale: number;
-  readonly estimatedAmountMinor: number;
-  readonly estimateKind: "catalog";
-}
-interface CostTrackingTelemetry {
-  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
-  forScope(scope: TelemetryScope): CostTrackingTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/runTypes.d.ts
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
-  message: string;
-  name?: string;
-  stack?: string;
-  details?: JsonValue;
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+  details?: JsonValue;
 }
 /** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
@@ -194,6 +247,9 @@ type ConnectionInvocationAppendArgs = Readonly<{
   queuedAt?: string;
   startedAt?: string;
   finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 interface PendingNodeExecution {
   runId: RunId;
@@ -229,275 +285,69 @@ type RunResult = {
   };
 };
 //#endregion
-//#region ../core/src/contracts/webhookTypes.d.ts
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-interface WebhookControlSignal {
-  readonly __webhookControl: true;
-  readonly kind: "respondNow" | "respondNowAndContinue";
-  readonly responseItems: Items;
-  readonly continueItems?: Items;
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
 }
-interface TriggerInstanceId {
-  workflowId: WorkflowId;
-  nodeId: NodeId;
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
 }
-//#endregion
-//#region ../core/src/workflow/dsl/workflowBuilderTypes.d.ts
-type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
-type AnyTriggerNodeConfig = TriggerNodeConfig<any>;
-type ValidStepSequence<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps extends readonly [] ? readonly [] : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? readonly [TFirst, ...ValidStepSequence<TNextJson, TRest>] : never : never : TSteps;
-type StepSequenceOutput<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? TSteps extends readonly [] ? TCurrentJson : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? StepSequenceOutput<TNextJson, TRest> : never : never : TCurrentJson : TCurrentJson;
-type TypesMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
-type BranchOutputGuard<TCurrentJson, TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TypesMatch<StepSequenceOutput<TCurrentJson, TTrueSteps>, StepSequenceOutput<TCurrentJson, TFalseSteps>> extends true ? unknown : never;
-type BranchStepsArg<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps & ValidStepSequence<TCurrentJson, TSteps>;
-type BranchMoreArgs<TCurrentJson, TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TRestSteps & ValidStepSequence<RunnableNodeOutputJson<TFirstStep>, TRestSteps>;
-type BooleanWhenOverloads<TCurrentJson, TReturn> = {
-  <TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, steps: BranchStepsArg<TCurrentJson, TSteps>): TReturn;
-  <TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, step: TFirstStep, ...more: BranchMoreArgs<TCurrentJson, TFirstStep, TRestSteps>): TReturn;
-};
-//#endregion
-//#region ../core/src/workflow/dsl/WhenBuilder.d.ts
-declare class WhenBuilder<TCurrentJson> {
-  private readonly wf;
-  private readonly from;
-  private readonly branchPort;
-  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey);
-  addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>): this;
-  readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>>;
-  build(): WorkflowDefinition;
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
 }
 //#endregion
-//#region ../core/src/workflow/dsl/ChainCursorResolver.d.ts
-type ChainCursorEndpoint = Readonly<{
-  node: NodeRef;
-  output: OutputPortKey;
-  inputPortHint?: InputPortKey;
+//#region ../core/src/contracts/workflowTypes.d.ts
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
 }>;
-type ChainCursorWhenOverloads<TCurrentJson> = BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> & {
-  <TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined>(branches: Readonly<{
-    true?: TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TTrueSteps> : never;
-    false?: TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TFalseSteps> : never;
-  }> & BranchOutputGuard<TCurrentJson, TTrueSteps, TFalseSteps>): ChainCursor<StepSequenceOutput<TCurrentJson, TTrueSteps>>;
-};
-declare class ChainCursor<TCurrentJson> {
-  private readonly wf;
-  private readonly endpoints;
-  constructor(wf: WorkflowBuilder, endpoints: ReadonlyArray<ChainCursorEndpoint>);
-  then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  thenIntoInputHints<TOutputJson$1, TConfig extends RunnableNodeConfig<any, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  readonly when: ChainCursorWhenOverloads<TCurrentJson>;
-  route<TNextJson$1>(branches: Readonly<Record<OutputPortKey, (branch: ChainCursor<TCurrentJson>) => ChainCursor<TNextJson$1> | undefined>>): ChainCursor<TNextJson$1>;
-  build(): WorkflowDefinition;
-  private resolveSharedInputPortHint;
-}
-//#endregion
-//#region ../core/src/workflow/dsl/WorkflowBuilder.d.ts
-declare class WorkflowBuilder {
-  private readonly meta;
-  private readonly options?;
-  private readonly nodes;
-  private readonly edges;
-  private seq;
-  constructor(meta: {
-    id: WorkflowId;
-    name: string;
-  }, options?: Readonly<Record<string, never>> | undefined);
-  private add;
-  private connect;
-  trigger<TConfig extends AnyTriggerNodeConfig>(config: TConfig): ChainCursor<TriggerNodeOutputJson<TConfig>>;
-  start<TConfig extends AnyRunnableNodeConfig>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  build(): WorkflowDefinition;
-}
-//#endregion
-//#region ../core/src/contracts/runtimeTypes.d.ts
-interface WorkflowRunnerService {
-  runById(args: {
-    workflowId: WorkflowId;
-    startAt?: NodeId;
-    items: Items;
-    parent?: ParentExecutionRef;
-  }): Promise<RunResult>;
-}
-interface NodeResolver {
-  resolve<T>(token: TypeToken<T>): T;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
 }
-interface NodeExecutionStatePublisher {
-  markQueued(args: {
-    nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-  }): Promise<void>;
-  markRunning(args: {
-    nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-  }): Promise<void>;
-  markCompleted(args: {
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
+type JsonNonArray = JsonPrimitive | JsonObject;
+interface Edge {
+  from: {
     nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-    outputs?: NodeOutputs;
-  }): Promise<void>;
-  markFailed(args: {
+    output: OutputPortKey;
+  };
+  to: {
     nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-    error: Error;
-  }): Promise<void>;
-  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+    input: InputPortKey;
+  };
 }
-type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
-interface BinaryStorageReadResult {
-  body: ReadableStream<Uint8Array>;
-  size?: number;
+/**
+ * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
+ * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
+ * also be connection-owned nodes for recursive agent attachments.
+ */
+interface WorkflowNodeConnection {
+  readonly parentNodeId: NodeId;
+  readonly connectionName: NodeConnectionName;
+  readonly childNodeIds: ReadonlyArray<NodeId>;
 }
-interface BinaryAttachmentCreateRequest {
-  name: string;
-  body: BinaryBody;
-  mimeType: string;
-  filename?: string;
-  previewKind?: BinaryAttachment["previewKind"];
-}
-interface NodeBinaryAttachmentService extends ExecutionBinaryService {
-  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
-  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
-}
-interface ExecutionBinaryService {
-  forNode(args: {
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }): NodeBinaryAttachmentService;
-  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
-}
-interface ExecutionContext {
-  runId: RunId;
-  workflowId: WorkflowId;
-  parent?: ParentExecutionRef;
-  /** This run's subworkflow depth (0 = root). */
-  subworkflowDepth: number;
-  /** Effective activation budget cap for this run (after policy merge). */
-  engineMaxNodeActivations: number;
-  /** Effective subworkflow nesting cap for this run (after policy merge). */
-  engineMaxSubworkflowDepth: number;
-  now: () => Date;
-  data: RunDataSnapshot;
-  nodeState?: NodeExecutionStatePublisher;
-  telemetry: ExecutionTelemetry;
-  binary: ExecutionBinaryService;
-  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
-}
-interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
-  nodeId: NodeId;
-  activationId: NodeActivationId;
-  config: TConfig;
-  telemetry: NodeExecutionTelemetry;
-  binary: NodeBinaryAttachmentService;
-}
-interface TriggerSetupContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
-  trigger: TriggerInstanceId;
-  config: TConfig;
-  previousState: TSetupState$1;
-  registerCleanup(cleanup: TriggerCleanupHandle): void;
-  emit(items: Items): Promise<void>;
-}
-interface TriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
-  trigger: TriggerInstanceId;
-  nodeId: NodeId;
-  config: TConfig;
-  previousState: TSetupState$1;
-}
-interface TriggerCleanupHandle {
-  stop(): Promise<void> | void;
-}
-/**
- * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}
- * for multi-port emission. Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input`
- * (wire `item.json` is unchanged). Transform helpers may opt into binary preservation, while routers and
- * pass-through nodes should return explicit items when they need to preserve full item state.
- */
-interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
-  readonly input: TInputJson$1;
-  readonly item: Item;
-  readonly itemIndex: number;
-  readonly items: Items;
-  readonly ctx: NodeExecutionContext<TConfig>;
-}
-interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
-  readonly kind: "node";
-  /**
-   * Declared output ports (e.g. `["main"]`).
-   *
-   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
-   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
-   */
-  readonly outputPorts?: ReadonlyArray<OutputPortKey>;
-  /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
-  readonly inputSchema?: ZodType<TInputJson$1>;
-  execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
-}
-interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
-  kind: "node";
-  /**
-   * Declared output ports (typically `["main"]`).
-   *
-   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
-   * Engine defaults to `["main"]` when omitted.
-   */
-  outputPorts?: ReadonlyArray<OutputPortKey>;
-  executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
-}
-type TriggerSetupStateFor<TConfig extends TriggerNodeConfig<any, any>> = TriggerNodeSetupState<TConfig>;
-interface TriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> {
-  kind: "trigger";
-  outputPorts: readonly ["main"];
-  setup(ctx: TriggerSetupContext<TConfig>): Promise<TriggerSetupStateFor<TConfig>>;
-  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
-}
-interface TestableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> extends TriggerNode<TConfig> {
-  getTestItems(ctx: TriggerTestItemsContext<TConfig>): Promise<Items>;
-}
-type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> = TriggerNode<TConfig>;
-//#endregion
-//#region ../core/src/contracts/workflowTypes.d.ts
-type WorkflowId = string;
-type NodeId = string;
-type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
-  __codemationNodeJson?: TJson;
-}>;
-type OutputPortKey = string;
-type InputPortKey = string;
-type NodeKind = "trigger" | "node";
-type JsonPrimitive = string | number | boolean | null;
-interface JsonObject {
-  readonly [key: string]: JsonValue;
-}
-type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-type JsonArray = ReadonlyArray<JsonValue>;
-/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
-type JsonNonArray = JsonPrimitive | JsonObject;
-interface Edge {
-  from: {
-    nodeId: NodeId;
-    output: OutputPortKey;
-  };
-  to: {
-    nodeId: NodeId;
-    input: InputPortKey;
-  };
-}
-type NodeConnectionName = string;
-/**
- * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
- * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
- * also be connection-owned nodes for recursive agent attachments.
- */
-interface WorkflowNodeConnection {
-  readonly parentNodeId: NodeId;
-  readonly connectionName: NodeConnectionName;
-  readonly childNodeIds: ReadonlyArray<NodeId>;
-}
-interface WorkflowDefinition {
-  id: WorkflowId;
+interface WorkflowDefinition {
+  id: WorkflowId;
   name: string;
   nodes: NodeDefinition[];
   edges: Edge[];
@@ -542,6 +392,14 @@ interface NodeConfigBase {
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+  /**
+   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
+   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
+   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
+   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
+   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
+   */
+  readonly emitsAssertions?: true;
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
@@ -571,6 +429,12 @@ interface TriggerNodeConfig<TOutputJson$1 = unknown, TSetupState$1 extends JsonV
   readonly kind: "trigger";
   readonly [triggerNodeOutputType]?: TOutputJson$1;
   readonly [triggerNodeSetupStateType]?: TSetupState$1;
+  /**
+   * Distinguishes triggers driven by the live activation policy (webhooks, cron, polling) from
+   * triggers driven only by the {@link TestSuiteOrchestrator}. `WorkflowActivation` skips
+   * `"test"` triggers; the orchestrator skips `"live"` triggers. Defaults to `"live"` when omitted.
+   */
+  readonly triggerKind?: "live" | "test";
 }
 type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
 type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
@@ -620,6 +484,12 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
+/**
+ * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
+ * per-item connection invocations and telemetry. Undefined when the executing node is a batch
+ * node or trigger that does not iterate items.
+ */
+type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
@@ -630,12 +500,21 @@ interface ParentExecutionRef {
   engineMaxNodeActivations?: number;
   /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
   engineMaxSubworkflowDepth?: number;
+  /**
+   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
+   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
+   * emitted inside a subworkflow land under the correct parent test case.
+   */
+  testContext?: RunTestContext;
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
   getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
   getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
+interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
 type UpstreamRefPlaceholder = `$${number}`;
 /** Whether to persist run execution data after the workflow finishes. */
 type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
@@ -683,155 +562,564 @@ interface NodeErrorHandler {
 }
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
-//#region ../core/src/contracts/credentialTypes.d.ts
-type CredentialTypeId = string;
-type CredentialInstanceId = string;
-type CredentialMaterialSourceKind = "db" | "env" | "code";
-type CredentialSetupStatus = "draft" | "ready";
-type CredentialHealthStatus = "unknown" | "healthy" | "failing";
-type CredentialFieldSchema = Readonly<{
-  key: string;
-  label: string;
-  type: "string" | "password" | "textarea" | "json" | "boolean";
-  required?: true;
-  order?: number;
+//#region ../core/src/contracts/testTriggerTypes.d.ts
+/**
+ * Identifier minted by the host (or in-memory test runner) for one execution of a test suite.
+ * One TestSuiteRun produces N child workflow runs, one per item yielded by `generateItems`.
+ */
+type TestSuiteRunId = string;
+/**
+ * Setup context passed to a {@link TestTriggerNodeConfig.generateItems} callback. Distinct from
+ * {@link import("./runtimeTypes").TriggerSetupContext} on purpose: test triggers are not
+ * activated by the live trigger lifecycle (webhooks, cron, polling) and never call `emit` —
+ * the orchestrator pulls from the iterable they return and dispatches one run per item.
+ */
+interface TestTriggerSetupContext<TConfig extends TestTriggerNodeConfig<unknown> = TestTriggerNodeConfig<unknown>> {
+  readonly workflowId: WorkflowId;
+  readonly nodeId: NodeId;
+  readonly config: TConfig;
+  readonly testSuiteRunId: TestSuiteRunId;
   /**
-   * Where this field appears in the credential dialog. Use `"advanced"` for optional or
-   * power-user fields; they render inside a collapsible section (see `CredentialTypeDefinition.advancedSection`).
-   * Defaults to `"default"` when omitted.
+   * Resolves a credential session for a slot declared on this trigger's
+   * {@link import("./workflowTypes").NodeConfigBase.getCredentialRequirements}. Same contract as
+   * {@link import("./runtimeTypes").ExecutionContext.getCredential}.
    */
-  visibility?: "default" | "advanced";
-  placeholder?: string;
-  helpText?: string;
-  /** When set, host resolves this field from process.env at runtime; env wins over stored values. */
-  envVarName?: string;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** AbortSignal raised when the suite is cancelled — long-running pulls should bail out. */
+  readonly signal: AbortSignal;
+}
+/**
+ * A trigger config that emits **test cases**. Each item yielded by {@link generateItems}
+ * becomes one workflow run (with `executionOptions.testContext` set), so 10 yielded items
+ * → 10 runs marked under the same TestSuiteRun.
+ *
+ * The trigger is otherwise a normal {@link TriggerNodeConfig} (so the canvas treats it like
+ * any other trigger), but its `triggerKind` is `"test"` so the live activation policy skips it.
+ */
+interface TestTriggerNodeConfig<TOutputJson$1 = unknown> extends TriggerNodeConfig<TOutputJson$1, undefined> {
+  readonly triggerKind: "test";
   /**
-   * When set, the dialog shows a copy action for this exact string (e.g. a static OAuth redirect URI
-   * pattern or documentation URL). Do not use for secret values.
+   * Author-supplied async iterable of items, evaluated lazily. Implementations may fetch from
+   * credentialed APIs, read fixture files, or yield hard-coded items. The orchestrator iterates
+   * and dispatches one run per item, with concurrency capped by {@link concurrency} (default 4).
    */
-  copyValue?: string;
-  /** Accessible label for the copy control (default: Copy). */
-  copyButtonLabel?: string;
-}>;
-type CredentialRequirement = Readonly<{
-  slotKey: string;
-  label: string;
-  acceptedTypes: ReadonlyArray<CredentialTypeId>;
-  optional?: true;
-  helpText?: string;
-  helpUrl?: string;
-}>;
-type CredentialHealth = Readonly<{
-  status: CredentialHealthStatus;
-  message?: string;
-  testedAt?: string;
-  expiresAt?: string;
-  details?: Readonly<Record<string, unknown>>;
-}>;
-type OAuth2ProviderFromPublicConfig = Readonly<{
-  authorizeUrlFieldKey: string;
-  tokenUrlFieldKey: string;
-  userInfoUrlFieldKey?: string;
-}>;
-type CredentialOAuth2ScopesFromPublicConfig = Readonly<{
-  presetFieldKey: string;
-  presetScopes: Readonly<Record<string, ReadonlyArray<string>>>;
-  customPresetKey?: string;
-  customScopesFieldKey?: string;
-}>;
-type CredentialOAuth2AuthDefinition = Readonly<{
-  kind: "oauth2";
-  providerId: string;
-  scopes: ReadonlyArray<string>;
-  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
-  clientIdFieldKey?: string;
-  clientSecretFieldKey?: string;
-} | {
-  kind: "oauth2";
-  providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
-  scopes: ReadonlyArray<string>;
-  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
-  clientIdFieldKey?: string;
-  clientSecretFieldKey?: string;
-}>;
-type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
-type CredentialAdvancedSectionPresentation = Readonly<{
-  /** Collapsible section title (default: "Advanced"). */
-  title?: string;
-  /** Optional short helper text shown inside the section (above the fields). */
-  description?: string;
-  /** When true, the advanced section starts expanded. Default: false (collapsed). */
-  defaultOpen?: boolean;
-}>;
-type CredentialTypeDefinition = Readonly<{
-  typeId: CredentialTypeId;
-  displayName: string;
-  description?: string;
-  publicFields?: ReadonlyArray<CredentialFieldSchema>;
-  secretFields?: ReadonlyArray<CredentialFieldSchema>;
+  generateItems(ctx: TestTriggerSetupContext<TestTriggerNodeConfig<TOutputJson$1>>): AsyncIterable<Item<TOutputJson$1>>;
+  /** Per-suite-run cap on simultaneously-executing test cases. Default: 4. */
+  readonly concurrency?: number;
   /**
-   * Optional labels for the collapsible block that contains every field with `visibility: "advanced"`.
-   * If omitted, the UI still shows that block with defaults (title "Advanced", collapsed).
+   * Free-form description of where the test cases come from — surfaced in the node properties
+   * panel and the suite-detail header so authors revisiting the workflow six months later
+   * remember which mailbox / folder / fixture file the cases originate from.
+   *
+   * Example: `"All emails in the Gmail label \"test/triage-fixtures\" — 14 messages as of 2026-05-03."`
    */
-  advancedSection?: CredentialAdvancedSectionPresentation;
-  supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
-  auth?: CredentialAuthDefinition;
-}>;
-/**
- * JSON-shaped credential field bag (public config, resolved secret material, etc.).
- */
-type CredentialJsonRecord = Readonly<Record<string, unknown>>;
+  readonly description?: string;
+  /**
+   * Resolves a human-readable label for one yielded test case (e.g. email subject). The
+   * orchestrator calls this once per yielded item, persists the result on the run, and the
+   * Tests-tab UI uses it to render the case row instead of the opaque runId. Return
+   * `undefined` to fall back to "Case #N".
+   */
+  caseLabel?(item: Item<TOutputJson$1>): string | undefined;
+}
+//#endregion
+//#region ../core/src/contracts/assertionTypes.d.ts
 /**
- * Persisted credential instance with typed `publicConfig`.
- * Hosts may specialize `secretRef` with a stricter union while remaining
- * assignable here for session/test callbacks.
+ * One assertion emitted by an assertion-emitting node (a node whose config sets
+ * `emitsAssertions: true`). Each emitted item on `main` carries one of these as `item.json`.
+ *
+ * Pass/fail is derived from `score >= (passThreshold ?? 0.5)` — see {@link deriveAssertionPassed}.
+ * The `errored` marker is for cases where the assertion code itself threw (distinct from
+ * "the assertion was evaluated and the score was low") and is treated as a hard fail in rollups
+ * regardless of `score`.
  */
-type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
-  instanceId: CredentialInstanceId;
-  typeId: CredentialTypeId;
-  displayName: string;
-  sourceKind: CredentialMaterialSourceKind;
-  publicConfig: TPublicConfig;
-  secretRef: CredentialJsonRecord;
-  tags: ReadonlyArray<string>;
-  setupStatus: CredentialSetupStatus;
-  createdAt: string;
-  updatedAt: string;
-}>;
+interface AssertionResult {
+  readonly name: string;
+  /** 0..1 score. Source of truth for pass/fail (compared against `passThreshold`). */
+  readonly score: number;
+  /** 0..1 threshold for "passed". When omitted, consumers default to 0.5. */
+  readonly passThreshold?: number;
+  /** True when evaluating the assertion threw — treated as fail regardless of `score`. */
+  readonly errored?: true;
+  /** What the assertion expected. Free-form JSON; UIs render with a JSON viewer. */
+  readonly expected?: JsonValue;
+  /** What the workflow actually produced. */
+  readonly actual?: JsonValue;
+  /** Short human-readable explanation, especially for fails / errors. */
+  readonly message?: string;
+  /** Bag of supplemental fields (e.g. judge prompt, judge raw response, comparison method). */
+  readonly details?: Readonly<Record<string, JsonValue>>;
+}
+//#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+  /**
+   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
+   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
+   *
+   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
+   * span instead of the orchestrator's node-level span.
+   */
+  asNodeTelemetry(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/webhookTypes.d.ts
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface WebhookControlSignal {
+  readonly __webhookControl: true;
+  readonly kind: "respondNow" | "respondNowAndContinue";
+  readonly responseItems: Items;
+  readonly continueItems?: Items;
+}
+interface TriggerInstanceId {
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+}
+//#endregion
+//#region ../core/src/contracts/collectionTypes.d.ts
 /**
- * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
- * Declare `TPublicConfig` / `TMaterial` on `CredentialType` so implementations are checked
- * against your credential shapes (similar to `NodeExecutionContext.config` for nodes).
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
  */
-type CredentialSessionFactoryArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
-  instance: CredentialInstanceRecord<TPublicConfig>;
-  material: TMaterial;
-  publicConfig: TPublicConfig;
+interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Insert a new row. id, created_at, and updated_at are auto-populated.
+   */
+  insert(row: TRow): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Get a single row by id.
+   */
+  get(id: string): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * Find a single row matching the provided filter.
+   */
+  findOne(filter: Partial<TRow>): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * List rows with optional pagination and filtering.
+   */
+  list(opts?: {
+    limit?: number;
+    offset?: number;
+    where?: Partial<TRow>;
+  }): Promise<{
+    rows: ReadonlyArray<TRow & {
+      id: string;
+      created_at: Date;
+      updated_at: Date;
+    }>;
+    total: number;
+  }>;
+  /**
+   * Update a row by id with partial data.
+   */
+  update(id: string, patch: Partial<TRow>): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Delete a row by id. Hard delete only (no soft delete).
+   */
+  delete(id: string): Promise<{
+    deleted: boolean;
+  }>;
+}
+/**
+ * Runtime collections context: keyed by collection name.
+ */
+type CollectionsContext = Readonly<Record<string, CollectionStore>>;
+//#endregion
+//#region ../core/src/contracts/emitPorts.d.ts
+declare const EMIT_PORTS_BRAND: unique symbol;
+type PortsEmission = Readonly<{
+  readonly [EMIT_PORTS_BRAND]: true;
+  readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
 }>;
-type CredentialSessionFactory<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
-type CredentialHealthTester<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<CredentialHealth>;
+//#endregion
+//#region ../core/src/workflow/dsl/workflowBuilderTypes.d.ts
+type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
+type AnyTriggerNodeConfig = TriggerNodeConfig<any>;
+type ValidStepSequence<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps extends readonly [] ? readonly [] : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? readonly [TFirst, ...ValidStepSequence<TNextJson, TRest>] : never : never : TSteps;
+type StepSequenceOutput<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? TSteps extends readonly [] ? TCurrentJson : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? StepSequenceOutput<TNextJson, TRest> : never : never : TCurrentJson : TCurrentJson;
+type TypesMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
+type BranchOutputGuard<TCurrentJson, TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TypesMatch<StepSequenceOutput<TCurrentJson, TTrueSteps>, StepSequenceOutput<TCurrentJson, TFalseSteps>> extends true ? unknown : never;
+type BranchStepsArg<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps & ValidStepSequence<TCurrentJson, TSteps>;
+type BranchMoreArgs<TCurrentJson, TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TRestSteps & ValidStepSequence<RunnableNodeOutputJson<TFirstStep>, TRestSteps>;
+type BooleanWhenOverloads<TCurrentJson, TReturn> = {
+  <TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, steps: BranchStepsArg<TCurrentJson, TSteps>): TReturn;
+  <TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, step: TFirstStep, ...more: BranchMoreArgs<TCurrentJson, TFirstStep, TRestSteps>): TReturn;
+};
+//#endregion
+//#region ../core/src/workflow/dsl/WhenBuilder.d.ts
+declare class WhenBuilder<TCurrentJson> {
+  private readonly wf;
+  private readonly from;
+  private readonly branchPort;
+  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey);
+  addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>): this;
+  readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>>;
+  build(): WorkflowDefinition;
+}
+//#endregion
+//#region ../core/src/workflow/dsl/ChainCursorResolver.d.ts
+type ChainCursorEndpoint = Readonly<{
+  node: NodeRef;
+  output: OutputPortKey;
+  inputPortHint?: InputPortKey;
+}>;
+type ChainCursorWhenOverloads<TCurrentJson> = BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> & {
+  <TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined>(branches: Readonly<{
+    true?: TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TTrueSteps> : never;
+    false?: TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TFalseSteps> : never;
+  }> & BranchOutputGuard<TCurrentJson, TTrueSteps, TFalseSteps>): ChainCursor<StepSequenceOutput<TCurrentJson, TTrueSteps>>;
+};
+declare class ChainCursor<TCurrentJson> {
+  private readonly wf;
+  private readonly endpoints;
+  constructor(wf: WorkflowBuilder, endpoints: ReadonlyArray<ChainCursorEndpoint>);
+  then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  thenIntoInputHints<TOutputJson$1, TConfig extends RunnableNodeConfig<any, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  readonly when: ChainCursorWhenOverloads<TCurrentJson>;
+  route<TNextJson$1>(branches: Readonly<Record<OutputPortKey, (branch: ChainCursor<TCurrentJson>) => ChainCursor<TNextJson$1> | undefined>>): ChainCursor<TNextJson$1>;
+  build(): WorkflowDefinition;
+  private resolveSharedInputPortHint;
+}
+//#endregion
+//#region ../core/src/workflow/dsl/WorkflowBuilder.d.ts
+declare class WorkflowBuilder {
+  private readonly meta;
+  private readonly options?;
+  private readonly nodes;
+  private readonly edges;
+  constructor(meta: {
+    id: WorkflowId;
+    name: string;
+  }, options?: Readonly<Record<string, never>> | undefined);
+  private add;
+  private connect;
+  trigger<TConfig extends AnyTriggerNodeConfig>(config: TConfig): ChainCursor<TriggerNodeOutputJson<TConfig>>;
+  start<TConfig extends AnyRunnableNodeConfig>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  build(): WorkflowDefinition;
+  private validateNodeIds;
+}
+//#endregion
+//#region ../core/src/contracts/runtimeTypes.d.ts
+interface WorkflowRunnerService {
+  runById(args: {
+    workflowId: WorkflowId;
+    startAt?: NodeId;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult>;
+}
+interface NodeResolver {
+  resolve<T>(token: TypeToken<T>): T;
+}
+interface NodeExecutionStatePublisher {
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+interface BinaryStorageReadResult {
+  body: ReadableStream<Uint8Array>;
+  size?: number;
+}
+interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+interface ExecutionBinaryService {
+  forNode(args: {
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  telemetry: ExecutionTelemetry;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
+  iterationId?: NodeIterationId;
+  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
+  itemIndex?: number;
+  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
+  parentInvocationId?: ConnectionInvocationId;
+  /**
+   * Present iff the run was started by a TestSuiteOrchestrator. The {@link IsTestRunNode}
+   * branches on this; assertion-emitting nodes use it to decide whether to record results.
+   */
+  testContext?: RunTestContext;
+  /**
+   * Collections registered in the codemation config, keyed by collection name.
+   */
+  readonly collections?: CollectionsContext;
+}
+interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  telemetry: NodeExecutionTelemetry;
+  binary: NodeBinaryAttachmentService;
+}
+interface PollingTriggerHandle {
+  /**
+   * Start the polling loop. The runtime registers its own cleanup handle so callers do not need to
+   * call {@link TriggerSetupContext.registerCleanup} for the loop.
+   * @returns The state returned by the first cycle (or `undefined` when the overlap guard fired).
+   */
+  start<TState, TItem>(args: {
+    intervalMs: number;
+    seedState?: TState;
+    runCycle: (cycleCtx: {
+      previousState: TState | undefined;
+      signal: AbortSignal;
+    }) => Promise<{
+      items: Items<TItem>;
+      nextState: TState;
+    }>;
+  }): Promise<TState | undefined>;
+  /** Convenience dedup-window helper. */
+  readonly dedup: PollingTriggerDedupWindow;
+}
+interface TriggerSetupContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  config: TConfig;
+  previousState: TSetupState$1;
+  registerCleanup(cleanup: TriggerCleanupHandle): void;
+  emit(items: Items): Promise<void>;
+  /** Generic polling-trigger surface. Pre-binds trigger id, emit, and registerCleanup. */
+  readonly polling: PollingTriggerHandle;
+}
+interface TriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  nodeId: NodeId;
+  config: TConfig;
+  previousState: TSetupState$1;
+}
+interface TriggerCleanupHandle {
+  stop(): Promise<void> | void;
+}
 /**
- * Full credential type implementation: `definition` (UI/schema), `createSession`, and `test`.
- * Use this at registration and config boundaries; `CredentialTypeDefinition` is only the schema slice.
+ * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}
+ * for multi-port emission. Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input`
+ * (wire `item.json` is unchanged). Transform helpers may opt into binary preservation, while routers and
+ * pass-through nodes should return explicit items when they need to preserve full item state.
  */
-type CredentialType<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = Readonly<{
-  definition: CredentialTypeDefinition;
-  createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
-  test: CredentialHealthTester<TPublicConfig, TMaterial>;
+interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
+  readonly input: TInputJson$1;
+  readonly item: Item;
+  readonly itemIndex: number;
+  readonly items: Items;
+  readonly ctx: NodeExecutionContext<TConfig>;
+}
+interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
+  readonly kind: "node";
+  /**
+   * Declared output ports (e.g. `["main"]`).
+   *
+   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
+   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
+   */
+  readonly outputPorts?: ReadonlyArray<OutputPortKey>;
+  /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
+}
+interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  /**
+   * Declared output ports (typically `["main"]`).
+   *
+   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
+   * Engine defaults to `["main"]` when omitted.
+   */
+  outputPorts?: ReadonlyArray<OutputPortKey>;
+  executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+type TriggerSetupStateFor<TConfig extends TriggerNodeConfig<any, any>> = TriggerNodeSetupState<TConfig>;
+interface TriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> {
+  kind: "trigger";
+  outputPorts: readonly ["main"];
+  setup(ctx: TriggerSetupContext<TConfig>): Promise<TriggerSetupStateFor<TConfig>>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+interface TestableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> extends TriggerNode<TConfig> {
+  getTestItems(ctx: TriggerTestItemsContext<TConfig>): Promise<Items>;
+}
+type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> = TriggerNode<TConfig>;
+//#endregion
+//#region ../core/src/contracts/itemExpr.d.ts
+declare const ITEM_EXPR_BRAND: unique symbol;
+type ItemExprResolvedContext = Readonly<{
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  data: RunDataSnapshot;
 }>;
 /**
- * Credential type with unspecified generics — used for `CodemationConfig.credentialTypes`, the host registry,
- * and anywhere a concrete `CredentialType<YourPublic, YourMaterial, YourSession>` is placed in a heterogeneous list.
- * Using `any` here avoids unsafe `as` casts while keeping typed `satisfies CredentialType<…>` definitions.
+ * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
  */
-type AnyCredentialType = CredentialType<any, any, unknown>;
-interface CredentialSessionService {
-  getSession<TSession = unknown>(args: Readonly<{
-    workflowId: WorkflowId;
-    nodeId: NodeId;
-    slotKey: string;
-  }>): Promise<TSession>;
-}
+type ItemExprContext = ItemExprResolvedContext;
+type ItemExprArgs<TItemJson = unknown> = Readonly<{
+  item: Item<TItemJson>;
+  itemIndex: number;
+  items: Items<TItemJson>;
+  ctx: ItemExprContext;
+}>;
+type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
+type ItemExpr<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_EXPR_BRAND]: true;
+  readonly fn: ItemExprCallback<T, TItemJson>;
+}>;
+//#endregion
+//#region ../core/src/contracts/params.d.ts
+type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
+type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
 //#endregion
 //#region ../core/src/authoring/defineNode.types.d.ts
 type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
@@ -897,6 +1185,15 @@ type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown>
   item: Item;
   itemIndex: number;
   items: Items;
+  /**
+   * Optional sub-agent boundary hooks: when present, the live `agent.tool.call` span and the
+   * planned tool-call invocationId are forwarded so node-backed runtimes can re-root their child
+   * execution scope. Plain function tools may safely ignore these hooks.
+   */
+  hooks?: Readonly<{
+    parentSpan?: TelemetrySpanScope;
+    parentInvocationId?: ConnectionInvocationId;
+  }>;
 }>;
 type AgentMessageRole = "system" | "user" | "assistant";
 type AgentMessageBuildArgs<TInputJson$1 = unknown> = Readonly<{
@@ -1024,6 +1321,32 @@ interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> exten
   readonly outputSchema?: ZodType<TOutputJson$1>;
 }
 //#endregion
+//#region ../core/src/execution/ChildExecutionScopeFactory.d.ts
+/**
+ * Builds a re-rooted child execution context for sub-agent (and other deeply-nested) invocations.
+ *
+ * At the orchestrator's `agent.tool.call` boundary the inner runtime needs a ctx whose:
+ * - `nodeId` is the tool's connection node id (so inner LLM/tool connection ids derive correctly),
+ * - `activationId` is fresh (so its connection-invocation rows are uniquely identifiable),
+ * - `telemetry` parents children under the tool-call span (not the orchestrator's node span),
+ * - `binary` is scoped to the new (nodeId, activationId),
+ * - `parentInvocationId` points back to the tool-call invocation for downstream lineage.
+ *
+ * Registered via factory in {@link EngineRuntimeRegistrar} so constructors stay free of parameter
+ * decorators (Next/SWC and coverage tooling cannot parse them on in-repo sources).
+ */
+declare class ChildExecutionScopeFactory {
+  private readonly activationIdFactory;
+  constructor(activationIdFactory: ActivationIdFactory);
+  forSubAgent<TConfig extends RunnableNodeConfig<any, any>>(args: Readonly<{
+    parentCtx: NodeExecutionContext<TConfig>;
+    childNodeId: NodeId;
+    childConfig: TConfig;
+    parentInvocationId: ConnectionInvocationId;
+    parentSpan: TelemetrySpanScope;
+  }>): NodeExecutionContext<TConfig>;
+}
+//#endregion
 //#region ../core/src/execution/ItemExprResolver.d.ts
 /**
  * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
@@ -1055,6 +1378,325 @@ declare class NodeOutputNormalizer {
   private applyOutput;
 }
 //#endregion
+//#region src/http/httpRequest.types.d.ts
+/**
+ * Binary reference key into `item.binary`.
+ */
+type BinaryRef = string;
+/**
+ * Discriminated union for the HTTP request body.
+ */
+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.
+ */
+interface CredentialSession {
+  applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
+}
+/**
+ * Mutations the credential session wants to apply to the outgoing request.
+ */
+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).
+ */
+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.
+ */
+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;
+}>;
+//#endregion
+//#region src/credentials/ApiKeyCredentialType.d.ts
+/**
+ * API key credential that injects a key either as an HTTP header or a query parameter.
+ */
+declare const apiKeyCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    placement: unknown;
+    name: unknown;
+  }, {
+    apiKey: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    placement: unknown;
+    name: unknown;
+  }, {
+    apiKey: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/BasicAuthCredentialType.d.ts
+/**
+ * HTTP Basic authentication credential.
+ * Session sets `Authorization: Basic <base64(username:password)>`.
+ */
+declare const basicAuthCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    username: unknown;
+  }, {
+    password: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    username: unknown;
+  }, {
+    password: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/BearerTokenCredentialType.d.ts
+/**
+ * Simple Bearer token credential.
+ * Session sets `Authorization: Bearer <token>` on every request.
+ */
+declare const bearerTokenCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<Readonly<Record<string, unknown>>, {
+    token: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<Readonly<Record<string, unknown>>, {
+    token: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/OAuth2ClientCredentialsTypeFactory.d.ts
+/**
+ * OAuth2 client-credentials flow credential.
+ *
+ * This is a machine-to-machine flow: no user redirect occurs. The session
+ * POSTs to the configured `tokenUrl` with `client_credentials` grant, caches
+ * the resulting access token for the duration of the session, and injects it
+ * as `Authorization: Bearer <token>` on each request.
+ *
+ * Token caching is per-session only (one createSession call = one token fetch
+ * at most). Cross-session caching would require host-level state and is out of
+ * scope here. Because the engine creates a fresh session per execution, a new
+ * token is fetched once per node activation.
+ *
+ * NOTE: `auth` is intentionally omitted from the definition. The OAuth2
+ * `auth: { kind: "oauth2" }` shape signals an authorization-code / user-redirect
+ * flow; using it here would cause the host UI to render an OAuth consent button
+ * that goes nowhere. Client-credentials is a purely server-side flow.
+ */
+declare const oauth2ClientCredentialsType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    tokenUrl: unknown;
+    scopes: unknown;
+    audience: unknown;
+  }, {
+    clientId: unknown;
+    clientSecret: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    tokenUrl: unknown;
+    scopes: unknown;
+    audience: unknown;
+  }, {
+    clientId: unknown;
+    clientSecret: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/authoring/defineRestNode.types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * API endpoint descriptor.
+ */
+type RestNodeApi = Readonly<{
+  /**
+   * Base URL, e.g. `"https://api.slack.com"`.
+   */
+  baseUrl: string;
+  /**
+   * Path relative to `baseUrl`. May contain `{paramName}` placeholders that
+   * are substituted from `input` keys before the request is made.
+   * Example: `"/users/{userId}/profile"`
+   */
+  path: string;
+  /** HTTP method (default: GET). */
+  method?: string;
+}>;
+/**
+ * The HTTP result shape passed into the `response` mapper.
+ */
+type RestNodeResponseContext = Readonly<{
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+}>;
+/**
+ * What the `request` callback may return to customise the request.
+ */
+type RestNodeRequestShape = Readonly<{
+  /** Additional path parameters to substitute (merged with `input`). */
+  pathParams?: Readonly<Record<string, string>>;
+  /** Extra query params. */
+  query?: Readonly<Record<string, string>>;
+  /** Extra headers. */
+  headers?: Readonly<Record<string, string>>;
+  /** Request body. */
+  body?: HttpBodySpec;
+}>;
+/**
+ * Error handling policy for non-2xx responses.
+ *  - `"throw"` (default) — throws an `Error` for non-2xx responses.
+ *  - `"passthrough"` — returns the result regardless of status.
+ */
+type RestNodeErrorPolicy = "throw" | "passthrough";
+interface DefineRestNodeOptions<TKey$1 extends string, TCredentials extends DefinedNodeCredentialBindings | undefined, TInputJson$1, TOutputJson$1> {
+  readonly key: TKey$1;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: string;
+  readonly api: RestNodeApi;
+  /**
+   * Credential bindings keyed by slot. Use the built-in credential types from
+   * `@codemation/core-nodes` (e.g. `bearerTokenCredentialType`) or any custom one.
+   * The slot key must match what the `request` callback's context uses.
+   */
+  readonly credentials?: TCredentials;
+  /**
+   * Zod schema for per-item input. Validated before `execute`.
+   */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  /**
+   * Builds the per-request customisations from the item input.
+   * Return `body`, `query`, `headers`, and/or `pathParams`.
+   */
+  request?(context: Readonly<{
+    input: TInputJson$1;
+  }>): MaybePromise<RestNodeRequestShape>;
+  /**
+   * Maps the HTTP response to the node's output JSON.
+   * When omitted, the output is `{ status, ok, statusText, mimeType, headers, json, text }`.
+   */
+  response?(context: RestNodeResponseContext & Readonly<{
+    input: TInputJson$1;
+  }>): MaybePromise<TOutputJson$1>;
+  /**
+   * How to handle non-2xx responses.
+   * @default "throw"
+   */
+  readonly errorPolicy?: RestNodeErrorPolicy;
+}
+/**
+ * Declarative helper for creating thin API-wrapper nodes.
+ *
+ * Usage:
+ * ```ts
+ * export const postMessage = defineRestNode({
+ *   key: "slack.post-message",
+ *   title: "Send Slack message",
+ *   icon: "si:slack",
+ *   api: { baseUrl: "https://slack.com/api", path: "/chat.postMessage", method: "POST" },
+ *   credentials: { auth: bearerTokenCredentialType },
+ *   inputSchema: z.object({ channel: z.string(), text: z.string() }),
+ *   request: ({ input }) => ({
+ *     body: { kind: "json", data: { channel: input.channel, text: input.text } },
+ *   }),
+ *   response: ({ json }) => ({ messageTs: (json as any).ts }),
+ * });
+ * ```
+ *
+ * - `defineRestNode` is a thin wrapper over `defineNode`; it does not introduce a new runtime kind.
+ * - Credential sessions are resolved via the `credentials` binding map (same as `defineNode`).
+ * - Path `{placeholder}` substitution is applied from `input` keys before the request is made.
+ * - Non-2xx responses throw an `Error` by default (`errorPolicy: "throw"`).
+ */
+declare function defineRestNode<TKey$1 extends string, TCredentials extends DefinedNodeCredentialBindings | undefined, TInputJson$1, TOutputJson$1 = RestNodeResponseContext>(options: DefineRestNodeOptions<TKey$1, TCredentials, TInputJson$1, TOutputJson$1>): DefinedNode<TKey$1, Record<string, never>, TInputJson$1, TOutputJson$1, TCredentials>;
+//#endregion
 //#region src/chatModels/openAiChatModelConfig.d.ts
 declare class OpenAIChatModelConfig implements ChatModelConfig {
   readonly name: string;
@@ -1205,19 +1847,31 @@ type ResolvedTool = Readonly<{
 }>;
 /**
  * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
- * original Zod `inputSchema` used to convert to AI SDK `Tool` + OpenAI-strict JSON Schema for
- * repair prompts.
+ * original Zod `inputSchema`.
+ *
+ * `execute` accepts optional `hooks` so the agent coordinator can pass the live `agent.tool.call`
+ * span and the planned tool-call's `invocationId`. Node-backed sub-agent tools use these hooks
+ * via {@link ChildExecutionScopeFactory} to re-root their runtime ctx under the tool-call boundary
+ * (fresh activationId, telemetry parented at the tool-call span, `parentInvocationId` set).
  */
 type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
-  execute(input: unknown): Promise<unknown>;
+  execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+}>;
+type ItemScopedToolCallHooks = Readonly<{
+  /** Live agent.tool.call span (used to parent sub-agent telemetry). */
+  parentSpan?: TelemetrySpanScope;
+  /** invocationId of the parent tool call (used to thread `parentInvocationId` through ctx). */
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 type PlannedToolCall = Readonly<{
   binding: ItemScopedToolBinding;
   toolCall: AgentToolCall;
   invocationIndex: number;
   nodeId: string;
+  /** Stable id reused across queued / running / completed connection invocation rows for this tool call. */
+  invocationId: string;
 }>;
 type ExecutedToolCall = Readonly<{
   toolName: string;
@@ -1442,8 +2096,24 @@ declare class NodeBackedToolRuntime {
   private readonly itemExprResolver;
   private readonly outputNormalizer;
   private readonly outputBehaviorResolver;
-  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
+  private readonly childExecutionScopeFactory;
+  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver, childExecutionScopeFactory: ChildExecutionScopeFactory);
   execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
+  /**
+   * Returns a re-rooted child ctx for nested-agent tools (so their LLM/tool connection ids derive
+   * from the tool connection node, telemetry parents under the tool-call span, and connection
+   * invocations carry `parentInvocationId`). Plain runnable tools (non-agent) keep the orchestrator
+   * ctx with only `config` swapped — no nesting concern.
+   *
+   * The caller (`AIAgentNode.createItemScopedTools`) already wraps the orchestrator ctx via
+   * `ConnectionCredentialExecutionContextFactory.forConnectionNode`, so `args.ctx.nodeId` is the
+   * tool's own connection node id (e.g. `AIAgentNode:2__conn__tool__searchInMail`). We pass that
+   * through as the sub-agent's `nodeId`; deriving another `toolConnectionNodeId(args.ctx.nodeId,
+   * config.name)` here would prepend a duplicate `__conn__tool__<name>` segment and exponentially
+   * deepen ids on each invocation, which also breaks credential resolution because user-provided
+   * bindings sit on the single-level connection node id.
+   */
+  private resolveNodeCtx;
   private executeResolvedNode;
   private isRunnableNode;
   private isMultiInputNode;
@@ -1510,6 +2180,14 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private invokeStructuredTurn;
   private isZodSchema;
   private resolveCallOptions;
+  /**
+   * Build a no-code-friendly output payload for an LLM round.
+   *
+   * Always includes `content` (matching the canvas snapshot shape used elsewhere) and adds a
+   * `toolCalls` array when the round produced tool calls so the execution inspector surfaces the
+   * planned calls instead of just an empty `""` for tool-only rounds.
+   */
+  private summarizeTurnOutput;
   private extractTurnResult;
   private extractAssistantMessage;
   private extractUsageFromResult;
@@ -1532,6 +2210,52 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private extractErrorDetails;
 }
 //#endregion
+//#region src/nodes/AssertionNode.d.ts
+/**
+ * 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.
+ */
+declare class AssertionNode implements RunnableNode<Assertion<any>> {
+  kind: "node";
+  outputPorts: readonly ["main"];
+  execute(args: RunnableNodeExecuteArgs<Assertion<any>>): Promise<unknown>;
+}
+//#endregion
+//#region src/nodes/assertion.d.ts
+interface AssertionOptions<TInputJson$1> {
+  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$1>, ctx: NodeExecutionContext<Assertion<TInputJson$1>>): 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.
+ */
+declare class Assertion<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, AssertionResult> {
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  readonly icon: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly emitsAssertions: true;
+  readonly assertions: AssertionOptions<TInputJson$1>["assertions"];
+  constructor(options: AssertionOptions<TInputJson$1>);
+}
+//#endregion
 //#region src/nodes/CallbackNode.d.ts
 declare class CallbackNode implements RunnableNode<Callback<any, any>> {
   kind: "node";
@@ -1576,10 +2300,12 @@ declare class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
   readonly outputPorts: readonly ["main"];
   execute(args: RunnableNodeExecuteArgs<HttpRequest<any, any>>): Promise<unknown>;
   private executeItem;
+  private resolveCredential;
   private resolveUrl;
   private asRecord;
   private readHeaders;
   private resolveMimeType;
+  private isJsonMimeType;
   private shouldAttachBody;
   private resolveFilename;
   private readFilenameFromContentDisposition;
@@ -1596,15 +2322,41 @@ type HttpRequestOutputJson = Readonly<{
   statusText: string;
   mimeType: string;
   headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
   bodyBinaryName?: string;
 }>;
+/**
+ * The built-in HTTP request credential type IDs accepted by the `HttpRequest` node.
+ * These match the four generic credential types shipped with `@codemation/core-nodes`.
+ */
+declare const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string>;
 declare class HttpRequest<TInputJson$1 = Readonly<{
   url?: string;
 }>, TOutputJson$1 = HttpRequestOutputJson> implements RunnableNodeConfig<TInputJson$1, TOutputJson$1> {
   readonly name: string;
   readonly args: Readonly<{
+    /** HTTP method (default: GET). */
     method?: string;
+    /**
+     * Legacy: field name on item.json to read the URL from.
+     * Use `url` for a literal/templated URL instead.
+     */
     urlField?: string;
+    /** Literal or templated URL. When present, takes precedence over `urlField`. */
+    url?: string;
+    /** Extra headers to add to every request. */
+    headers?: Readonly<Record<string, string>>;
+    /** Query parameters to append to the URL. */
+    query?: Readonly<Record<string, string>>;
+    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    body?: HttpBodySpec;
+    /**
+     * Credential slot key. When set, the node resolves a credential via
+     * `ctx.getCredential(credentialSlot)` and applies it to the request.
+     * The slot must be declared in `getCredentialRequirements()`.
+     */
+    credentialSlot?: string;
     binaryName?: string;
     downloadMode?: HttpRequestDownloadMode;
     id?: string;
@@ -1617,8 +2369,27 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
   };
   readonly icon: "lucide:globe";
   constructor(name: string, args?: Readonly<{
+    /** HTTP method (default: GET). */
     method?: string;
+    /**
+     * Legacy: field name on item.json to read the URL from.
+     * Use `url` for a literal/templated URL instead.
+     */
     urlField?: string;
+    /** Literal or templated URL. When present, takes precedence over `urlField`. */
+    url?: string;
+    /** Extra headers to add to every request. */
+    headers?: Readonly<Record<string, string>>;
+    /** Query parameters to append to the URL. */
+    query?: Readonly<Record<string, string>>;
+    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    body?: HttpBodySpec;
+    /**
+     * Credential slot key. When set, the node resolves a credential via
+     * `ctx.getCredential(credentialSlot)` and applies it to the request.
+     * The slot must be declared in `getCredentialRequirements()`.
+     */
+    credentialSlot?: string;
     binaryName?: string;
     downloadMode?: HttpRequestDownloadMode;
     id?: string;
@@ -1628,6 +2399,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
   get urlField(): string;
   get binaryName(): string;
   get downloadMode(): HttpRequestDownloadMode;
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
 }
 //#endregion
 //#region src/nodes/AggregateNode.d.ts
@@ -1694,6 +2466,38 @@ declare class If<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJso
   constructor(name: string, predicate: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<If<TInputJson$1>>) => boolean, id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/IsTestRunNode.d.ts
+/**
+ * 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
+ */
+declare class IsTestRunNode implements RunnableNode<IsTestRun<unknown>> {
+  kind: "node";
+  execute(args: RunnableNodeExecuteArgs<IsTestRun<unknown>>): unknown;
+}
+//#endregion
+//#region src/nodes/isTestRun.d.ts
+/**
+ * Branches per-item on whether the current run is a test run. Output ports: `true`, `false`.
+ * The wire payload is unchanged — this is a router, not a transform.
+ */
+declare class IsTestRun<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, TInputJson$1> {
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  readonly execution: {
+    readonly hint: "local";
+  };
+  readonly icon: "lucide:flask-conical";
+  readonly declaredOutputPorts: readonly ["true", "false"];
+  readonly name: string;
+  readonly id?: string;
+  constructor(name?: string, id?: string);
+}
+//#endregion
 //#region src/nodes/SwitchNode.d.ts
 /**
  * Routes each item to exactly one output port. Port names must match workflow edges (see {@link Switch} config).
@@ -1754,6 +2558,45 @@ declare class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfi
   constructor(name: string, getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[], id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/CronTriggerFactory.d.ts
+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.
+ */
+declare class CronTrigger implements TriggerNodeConfig<CronTickJson> {
+  readonly name: string;
+  private readonly args;
+  readonly kind: "trigger";
+  readonly type: TypeToken<unknown>;
+  readonly icon: "lucide:clock";
+  readonly id?: string;
+  constructor(name: string, args: Readonly<{
+    schedule: string;
+    timezone?: string;
+  }>, id?: string);
+  get schedule(): string;
+  get timezone(): string | undefined;
+  createJob(callback: CronCallback): Cron;
+}
+//#endregion
+//#region src/nodes/CronTriggerNode.d.ts
+declare class CronTriggerNode implements TestableTriggerNode<CronTrigger> {
+  readonly kind: "trigger";
+  readonly outputPorts: readonly ["main"];
+  setup(ctx: TriggerSetupContext<CronTrigger>): Promise<undefined>;
+  execute(items: Items, _ctx: NodeExecutionContext<CronTrigger>): Promise<NodeOutputs>;
+  getTestItems(ctx: TriggerTestItemsContext<CronTrigger>): Promise<Items>;
+}
+//#endregion
 //#region src/nodes/ManualTriggerNode.d.ts
 /**
  * Setup is intentionally a no-op: the engine host can run workflows manually
@@ -1894,6 +2737,71 @@ declare class SubWorkflow<TInputJson$1 = unknown, TOutputJson$1 = unknown> imple
   } | UpstreamRefPlaceholder> | undefined, startAt?: NodeId | undefined, id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/TestTriggerNode.d.ts
+/**
+ * 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`.
+ */
+declare class TestTriggerNode implements TriggerNode<TestTriggerNodeConfig<any>> {
+  kind: "trigger";
+  outputPorts: readonly ["main"];
+  setup(_ctx: TriggerSetupContext<TestTriggerNodeConfig<any>>): Promise<undefined>;
+  execute(items: Items, _ctx: NodeExecutionContext<TestTriggerNodeConfig<any>>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region src/nodes/testTrigger.d.ts
+interface TestTriggerOptions<TOutputJson$1> {
+  readonly name?: string;
+  readonly id?: string;
+  readonly icon?: string;
+  /** Cap on simultaneous in-flight test cases for one suite run. Default: 4 (orchestrator). */
+  readonly concurrency?: number;
+  readonly credentialRequirements?: ReadonlyArray<CredentialRequirement>;
+  /**
+   * Free-form description of where the test cases come from. Shown in the node properties
+   * panel and the Tests-tab suite-detail header so authors revisiting the workflow six months
+   * later remember which mailbox / folder / fixture file the cases originate from.
+   */
+  readonly description?: string;
+  /**
+   * Author callback that yields one item per test case. Items are dispatched as separate
+   * workflow runs by the TestSuiteOrchestrator, with `executionOptions.testContext` set.
+   * The provided context exposes credential resolution and an AbortSignal for cancellation.
+   */
+  generateItems(ctx: TestTriggerSetupContext<TestTrigger<TOutputJson$1>>): AsyncIterable<Item<TOutputJson$1>>;
+  /**
+   * Optional resolver: extract a human-readable label from a yielded item. The orchestrator
+   * persists this on the run, so the Tests-tab tree-table shows e.g. "RFQ for batch 14"
+   * instead of an opaque runId. Typical use: `(item) => item.json.subject` for mailbox tests.
+   */
+  caseLabel?(item: Item<TOutputJson$1>): string | undefined;
+}
+/**
+ * Trigger config for a test fixture source. Drop one (or more) of these on the canvas alongside
+ * a workflow's live triggers; clicking "Run tests" on the Tests tab invokes
+ * {@link TestTriggerOptions.generateItems} via the TestSuiteOrchestrator.
+ */
+declare class TestTrigger<TOutputJson$1 = unknown> implements TestTriggerNodeConfig<TOutputJson$1> {
+  readonly kind: "trigger";
+  readonly triggerKind: "test";
+  readonly type: TypeToken<unknown>;
+  readonly icon: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly concurrency?: number;
+  readonly description?: string;
+  readonly generateItems: TestTriggerOptions<TOutputJson$1>["generateItems"];
+  readonly caseLabel?: TestTriggerOptions<TOutputJson$1>["caseLabel"];
+  private readonly credentialRequirements;
+  constructor(options: TestTriggerOptions<TOutputJson$1>);
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
+}
+//#endregion
 //#region src/nodes/WaitDurationFactory.d.ts
 declare class WaitDuration {
   static normalize(milliseconds: number): number;
@@ -2138,5 +3046,67 @@ declare class AIAgentConnectionWorkflowExpander {
   private assertNoIdCollision;
 }
 //#endregion
-export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, type ExecutedToolCall, Filter, FilterNode, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, type ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, Split, SplitNode, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, createWorkflowBuilder, openAiChatModelPresets, registerCoreNodes, workflow };
+//#region src/nodes/collections/collectionInsertNode.types.d.ts
+declare const collectionInsertNode: DefinedNode<"collection-insert", {
+  collectionName: string;
+  data: Record<string, unknown>;
+}, unknown, Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}, undefined>;
+//#endregion
+//#region src/nodes/collections/collectionGetNode.types.d.ts
+declare const collectionGetNode: DefinedNode<"collection-get", {
+  collectionName: string;
+  id: string;
+}, unknown, never[] | (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}), undefined>;
+//#endregion
+//#region src/nodes/collections/collectionFindOneNode.types.d.ts
+declare const collectionFindOneNode: DefinedNode<"collection-find-one", {
+  collectionName: string;
+  where: Record<string, unknown>;
+}, unknown, never[] | (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}), undefined>;
+//#endregion
+//#region src/nodes/collections/collectionListNode.types.d.ts
+declare const collectionListNode: DefinedNode<"collection-list", {
+  collectionName: string;
+  limit?: number | undefined;
+  offset?: number | undefined;
+  where?: Record<string, unknown> | undefined;
+}, unknown, (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+})[], undefined>;
+//#endregion
+//#region src/nodes/collections/collectionUpdateNode.types.d.ts
+declare const collectionUpdateNode: DefinedNode<"collection-update", {
+  collectionName: string;
+  id: string;
+  patch: Record<string, unknown>;
+}, unknown, Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}, undefined>;
+//#endregion
+//#region src/nodes/collections/collectionDeleteNode.types.d.ts
+declare const collectionDeleteNode: DefinedNode<"collection-delete", {
+  collectionName: string;
+  id: string;
+}, unknown, {
+  deleted: boolean;
+  id: string;
+}, undefined>;
+//#endregion
+export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DefineRestNodeOptions, type ExecutedToolCall, Filter, FilterNode, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, type ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, Split, SplitNode, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, apiKeyCredentialType, basicAuthCredentialType, bearerTokenCredentialType, collectionDeleteNode, collectionFindOneNode, collectionGetNode, collectionInsertNode, collectionListNode, collectionUpdateNode, createWorkflowBuilder, defineRestNode, oauth2ClientCredentialsType, openAiChatModelPresets, registerCoreNodes, workflow };
 //# sourceMappingURL=index.d.ts.map