@codemation/core 0.14.0 → 0.15.0

package/src/authoring/defineHumanApprovalNode.types.ts

@@ -15,69 +15,27 @@ import { SuspensionRequest } from "../contracts/runtimeTypes";
 import { defineNode } from "./defineNode.types";
 import type { DefinedNode } from "./defineNode.types";
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/**
- * Decision shape merged into `item.json` after a HITL approval task resolves.
- *
- * - `"approved"` / `"rejected"` — from a human decision (uses `approvedPredicate`).
- * - `"timed-out"` — timeout fired with `onTimeout: "halt"`.
- * - `"auto-accepted"` — timeout fired with `onTimeout: "auto-accept"`.
- */
 export interface HumanApprovalDecisionResult {
   readonly status: "approved" | "rejected" | "timed-out" | "auto-accepted";
-  /** Identity of the person who decided; absent for automated outcomes. */
   readonly actor?: HumanTaskActor;
-  /** ISO 8601 timestamp of the decision. */
   readonly decidedAt?: Date;
-  /** Optional free-text note from the reviewer. */
   readonly note?: string;
-  /**
-   * Full raw decision payload (only present for `"approved"` / `"rejected"`).
-   * Shape is determined by the channel's `decisionSchema`.
-   */
   readonly payload?: Record<string, unknown>;
 }
 
-/**
- * Output item shape emitted by a `defineHumanApprovalNode`-based node.
- * Original `item.json` fields are preserved and `decision` is merged in.
- * If the input `item.json` already contained a `decision` key it is **overwritten**.
- */
 export type HumanApprovalOutputJson<TInputJson extends Record<string, unknown>> = TInputJson & {
   readonly decision: HumanApprovalDecisionResult;
 };
 
-/**
- * Extends {@link DefinedNode} with the `humanApprovalToolBehavior` metadata marker.
- * Story 10 reads this field when attaching the node as an agent tool.
- */
 export interface DefinedHumanApprovalNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson extends Record<string, unknown>,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 > extends DefinedNode<TKey, TConfig, TInputJson, HumanApprovalOutputJson<TInputJson>, TBindings> {
-  /**
-   * Behavior hint consumed by the agent runtime (story 10) when this node is attached as a tool.
-   * `"return"` (default) — return the rejection to the agent as a tool result.
-   * `"halt"` — halt the agent run on rejection.
-   *
-   * Standalone DSL usage ignores this field.
-   */
   readonly humanApprovalToolBehavior: { onRejected: "return" | "halt" };
 }
 
-// ---------------------------------------------------------------------------
-// isHumanApprovalNode predicate
-// ---------------------------------------------------------------------------
-
-/**
- * Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
- * Uses the `humanApprovalToolBehavior` typed field as the discriminant.
- */
 export function isHumanApprovalNode(
   node: unknown,
 ): node is DefinedHumanApprovalNode<string, Record<string, unknown>, Record<string, unknown>, undefined> {
@@ -89,57 +47,6 @@ export function isHumanApprovalNode(
   );
 }
 
-// ---------------------------------------------------------------------------
-// defineHumanApprovalNode
-// ---------------------------------------------------------------------------
-
-/**
- * Authoring helper that compiles a HITL approval channel down to a regular
- * {@link defineNode}-backed node with `SuspensionRequest` semantics.
- *
- * **Fast-forward decision semantics:**
- * - On the first `execute` call (no `ctx.resumeContext`): throws a `SuspensionRequest`
- *   that calls the author's `deliver`. The engine persists the suspension and continues.
- * - On resume (`ctx.resumeContext` set): calls `onDecision`/`onTimeout` as appropriate,
- *   merges a `decision` key into `item.json`, and returns an item with the original
- *   `binary` map passed by reference (no copy).
- *
- * **Output shape per item:**
- * ```ts
- * // Input:  { json: { invoiceId: 42 }, binary?: {...} }
- * // Output: { json: { invoiceId: 42, decision: { status: "approved", actor, decidedAt } }, binary: <unchanged> }
- * ```
- * If `item.json` already has a `decision` key it is **overwritten**. Namespace as
- * needed if your schema reserves that key for another purpose.
- *
- * **Predicate persistence:**
- * The `approvedPredicate` function is NOT serialized to the suspension record (except
- * as an audit-only string via `toString()`). On resume, the workflow definition is
- * reloaded from code at process start and the predicate closure is rebuilt naturally.
- * If a deploy ships a changed predicate between suspend and resume, the *new* predicate
- * runs — document this in your runbook when the predicate carries business logic that
- * may change across deploys.
- *
- * @example
- * ```ts
- * export const slackApprovalNode = defineHumanApprovalNode({
- *   key: "my-plugin.slackApproval",
- *   title: "Slack Approval",
- *   channel: "slack",
- *   configSchema: z.object({ channel: z.string(), message: z.string() }),
- *   decisionSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
- *
- *   async deliver({ task, config, item }, ctx) {
- *     const ts = await postSlackMessage(config.channel, `Approve? <${task.resumeUrl}>`);
- *     return { channel: config.channel, ts };
- *   },
- *
- *   async onDecision({ decision, actor, delivery }, ctx) {
- *     await updateSlackMessage(delivery.channel, delivery.ts, decision.approved ? "✅" : "❌");
- *   },
- * });
- * ```
- */
 export function defineHumanApprovalNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -159,16 +66,8 @@ export function defineHumanApprovalNode<
   decisionSchema: ZodType<TDecision>;
   credentials?: TBindings;
 
-  /**
-   * Custom predicate that decides whether a decision counts as "approved".
-   * When omitted, the helper checks if `decisionSchema` is a Zod object with an
-   * `approved: boolean` field; if so it uses `decision.approved === true`.
-   * If neither holds, `defineHumanApprovalNode` throws at **definition time** (not runtime).
-   */
   approvedPredicate?: (decision: TDecision) => boolean;
-  /** Default suspension timeout. Defaults to `"24h"`. */
   defaultTimeout?: Duration;
-  /** What to do when the task times out. Defaults to `"halt"`. */
   defaultOnTimeout?: "halt" | "auto-accept";
 
   inspectorSummary?: (config: TConfig) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
@@ -204,16 +103,11 @@ export function defineHumanApprovalNode<
     ctx: ExecutionContext,
   ) => Promise<void>;
 }): DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings> {
-  // Resolve the approved predicate at definition time so we throw early when
-  // the schema is ambiguous.
   const resolvedPredicate = resolveApprovedPredicate(opts.decisionSchema, opts.approvedPredicate);
 
   const timeout = opts.defaultTimeout ?? "24h";
   const onTimeout = opts.defaultOnTimeout ?? "halt";
 
-  // TOutputJson is `unknown` here because `execute` returns an Item-shaped object
-  // that the engine's NodeOutputNormalizer converts to the proper output. The public
-  // interface's DefinedHumanApprovalNode carries the correct output type for DSL use.
   const inner = defineNode<TKey, TConfig, TInputJson, unknown, TBindings>({
     key: opts.key,
     title: opts.title,
@@ -226,7 +120,6 @@ export function defineHumanApprovalNode<
 
     async execute(args, { config, execution: ctx }) {
       if (!ctx.resumeContext) {
-        // First pass — suspend.
         const subject = buildSubject(opts.title, args.item, ctx);
         throw new SuspensionRequest({
           decisionSchema: opts.decisionSchema,
@@ -236,7 +129,6 @@ export function defineHumanApprovalNode<
           metadata: {
             channel: opts.channel,
             nodeKey: opts.key,
-            // Stored for audit only; never re-evaluated. See JSDoc on defineHumanApprovalNode.
             approvedPredicateSource: opts.approvedPredicate?.toString() ?? null,
           },
           deliver: (handle: HumanTaskHandle) =>
@@ -252,7 +144,6 @@ export function defineHumanApprovalNode<
         });
       }
 
-      // Resume pass.
       return await handleResume(
         args.item,
         ctx.resumeContext,
@@ -270,10 +161,6 @@ export function defineHumanApprovalNode<
   }) as unknown as DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings>;
 }
 
-// ---------------------------------------------------------------------------
-// Internal helpers (module-private)
-// ---------------------------------------------------------------------------
-
 function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
   schema: ZodType<TDecision>,
   predicate: ((d: TDecision) => boolean) | undefined,
@@ -281,7 +168,6 @@ function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
   if (predicate) {
     return predicate;
   }
-  // Zod 4: ZodObject exposes `.shape` directly as an object (not a function).
   const shape = (schema as unknown as ZodObject<Record<string, ZodType>>).shape;
   if (shape && typeof shape === "object" && "approved" in shape) {
     return (d) => (d as { approved?: unknown }).approved === true;
@@ -310,7 +196,6 @@ function mergeDecision(
 ): { json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] } {
   return {
     json: { ...(item.json as Record<string, unknown>), decision },
-    // binary is passed by reference — no copy. See defineHumanApprovalNode JSDoc.
     binary: item.binary,
     meta: item.meta,
   };
@@ -355,7 +240,6 @@ async function handleResume<TDecision extends Record<string, unknown>, TDelivery
     return mergeDecision(item, { status, decidedAt: dec.at });
   }
 
-  // dec.kind === "decided"
   const parsed = decisionSchema.parse(dec.value);
   await onDecision?.(
     {

package/src/authoring/defineNode.types.ts

@@ -57,10 +57,6 @@ export interface DefinedNodeRunContext<
   readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
 }
 
-/**
- * Arguments for {@link defineNode} `execute` (engine `ctx` matches {@link RunnableNode.execute};
- * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
- */
 export type DefineNodeExecuteArgs<TConfig extends CredentialJsonRecord, TInputJson> = Readonly<{
   input: TInputJson;
   item: Item;
@@ -93,9 +89,6 @@ export interface DefinedNode<
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
-/**
- * Plugin / DSL-friendly node: per-item `execute` with optional {@link RunnableNodeConfig.inputSchema}.
- */
 export interface DefineNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -106,27 +99,12 @@ export interface DefineNodeOptions<
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  /**
-   * Canvas icon for this node (same contract as `NodeConfigBase.icon` on runnable configs).
-   * The Next host resolves Lucide (`lucide:…`), built-in SVGs (`builtin:…`), Simple Icons (`si:…`), and image URLs (`https:`, `data:`, `/…`).
-   */
   readonly icon?: string;
-  /** Default values / form hints for **static** node configuration (credentials, retry, IDs), not per-item payload. */
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
-  /**
-   * Validates **`input`** (engine also accepts `inputSchema` on the node class).
-   */
   readonly inputSchema?: ZodType<TInputJson>;
-  /** Preserve inbound `item.binary` when `execute` returns plain JSON or item-shaped results without `binary`. */
   readonly keepBinaries?: boolean;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — see
-   * {@link import("../contracts/workflowTypes").NodeConfigBase.inspectorSummary}.
-   *
-   * Receives the static config; returns 2–6 short label/value pairs (or `undefined` to skip).
-   */
   readonly inspectorSummary?: (
     args: Readonly<{ config: TConfig }>,
   ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
@@ -136,9 +114,6 @@ export interface DefineNodeOptions<
   ): MaybePromise<TOutputJson>;
 }
 
-/**
- * Batch-oriented defined node: `run` receives all item JSON once (last item in activation); emits one output per input row.
- */
 export interface DefineBatchNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,

package/src/authoring/definePollingTrigger.types.ts

@@ -1,18 +1,11 @@
-/**
- * definePollingTrigger — declarative helper for authoring polling triggers.
- *
- * Mirrors the ergonomics of `defineNode` / `defineRestNode` / `defineCredential`.
- * Plugin authors supply a `poll` function plus metadata; the helper synthesises the
- * two internal classes (`DefinedPollingTriggerRuntime` + `DefinedPollingTriggerConfig`)
- * that the engine's trigger machinery requires. Internal classes, DI annotations, and
- * `PollingTriggerRuntime` wiring are hidden from the plugin-author surface entirely.
- */
 import type {
   Items,
+  JsonObject,
   JsonValue,
   NodeExecutionContext,
   NodeInspectorSummaryRow,
   NodeOutputs,
+  PollingTriggerConfig,
   TestableTriggerNode,
   TriggerNodeConfig,
   TriggerSetupContext,
@@ -29,15 +22,8 @@ import {
 } from "./definePollingTriggerInternals";
 import type { ZodType } from "zod";
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
 type MaybePromise<TValue> = TValue | Promise<TValue>;
 
-/**
- * Context passed into the `poll` callback on each tick.
- */
 export interface DefinePollingTriggerPollContext<
   TConfig extends CredentialJsonRecord,
   TState extends JsonValue | undefined,
@@ -48,36 +34,17 @@ export interface DefinePollingTriggerPollContext<
   readonly credentials: DefinedNodeCredentialAccessors<TBindings>;
 }
 
-/**
- * What `poll` must return each tick.
- */
 export interface DefinePollingTriggerPollResult<TItemJson, TState extends JsonValue | undefined> {
-  /**
-   * New items to emit. Each item may carry an optional `dedupKey`; duplicate keys are
-   * filtered out against a rolling dedup window (managed internally by the runtime).
-   * Items without a `dedupKey` are always emitted.
-   */
   readonly items: ReadonlyArray<{ json: TItemJson; dedupKey?: string }>;
-  /** Persisted as the trigger's setup state for the next tick. */
   readonly nextState: TState;
 }
 
-/**
- * Context passed into the `execute` callback for post-emit enrichment (e.g. fetching
- * attachment bytes). Mirrors `NodeExecutionContext` so plugin authors use familiar patterns.
- */
 export type DefinePollingTriggerExecuteContext<TConfig extends TriggerNodeConfig<any, any>> =
   NodeExecutionContext<TConfig>;
 
-/**
- * Context passed into the `testItems` callback.
- */
 export type DefinePollingTriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any>> =
   TriggerTestItemsContext<TConfig>;
 
-/**
- * Options accepted by `definePollingTrigger`.
- */
 export interface DefinePollingTriggerOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -85,77 +52,30 @@ export interface DefinePollingTriggerOptions<
   TState extends JsonValue | undefined,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 > {
-  /**
-   * Unique node-token-id-style key, e.g. `"msgraph-mail.on-new-mail"`.
-   * Used as the persisted runtime type name — must be stable across deployments.
-   */
   readonly key: TKey;
+  readonly packageName?: string;
   readonly title: string;
   readonly description?: string;
-  /** Canvas icon (same contract as `NodeConfigBase.icon`). */
   readonly icon?: string;
-  /**
-   * Zod schema for the trigger's user-facing configuration.
-   * When provided, the returned `create()` method is typed against the inferred config type.
-   */
   readonly configSchema?: ZodType<TConfig>;
-  /** Credential bindings keyed by slot (same format as `defineNode`). */
   readonly credentials?: TBindings;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — see
-   * {@link import("../contracts/workflowTypes").NodeConfigBase.inspectorSummary}.
-   *
-   * Receives the static config; returns 2–6 short label/value pairs (or `undefined` to skip).
-   */
   readonly inspectorSummary?: (
     args: Readonly<{ config: TConfig }>,
   ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
-  /**
-   * Called once when the trigger arms (or re-arms after a server restart) to provide the
-   * initial value for `state` when no persisted state exists.
-   */
   initialState?(): TState;
-  /**
-   * Polling interval in milliseconds. The runtime enforces a minimum of 25 ms.
-   * @default 60_000
-   */
   readonly pollIntervalMs?: number;
-  /**
-   * The per-tick poll logic. Called by the runtime each interval.
-   * Must return new items plus the next persisted state.
-   */
   poll(
     pollCtx: DefinePollingTriggerPollContext<TConfig, TState, TBindings>,
   ): MaybePromise<DefinePollingTriggerPollResult<TItemJson, TState>>;
-  /**
-   * Optional post-emit enrichment step (runs in the normal node-execute phase after the
-   * trigger fires and the workflow run starts). Use for expensive per-item work such as
-   * fetching attachment bytes via `ctx.binary.attach`. When omitted, the trigger passes
-   * items through unchanged.
-   */
   execute?(
     items: Items<TItemJson>,
     ctx: NodeExecutionContext<DefinedPollingTriggerConfig<TConfig, TItemJson>>,
   ): MaybePromise<NodeOutputs>;
-  /**
-   * Optional implementation for the workflow UI's "Test" button. Should return a small
-   * sample of current items without consulting or mutating polling state.
-   */
   testItems?(
     ctx: TriggerTestItemsContext<DefinedPollingTriggerConfig<TConfig, TItemJson>>,
   ): MaybePromise<Items<TItemJson>>;
 }
 
-// ---------------------------------------------------------------------------
-// DefinedPollingTrigger (returned object)
-// ---------------------------------------------------------------------------
-
-/**
- * The object returned by `definePollingTrigger`. Register it via
- * `definePlugin({ nodes: [myTrigger] })` or call `.register(ctx)` directly.
- *
- * `poll` is also directly callable for unit-testing — no runtime needed.
- */
 export interface DefinedPollingTrigger<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -167,45 +87,22 @@ export interface DefinedPollingTrigger<
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  /**
-   * Create the trigger config for use in workflow definitions.
-   * @param cfg - User-facing trigger configuration.
-   * @param name - Display name (defaults to `title`).
-   * @param idOrOptions - Optional stable node id, or `{ id?, description? }` authoring options
-   *   (a bare string id still works — back-compat).
-   */
   create(
     cfg: TConfig,
     name?: string,
     idOrOptions?: string | NodeBaseOptions,
   ): DefinedPollingTriggerConfig<TConfig, TItemJson>;
-  /**
-   * Test seam: call `poll` directly without starting the runtime.
-   * Returns `{ items, nextState }` just like the real runtime receives.
-   */
   poll(
     pollCtx: Omit<DefinePollingTriggerPollContext<TConfig, TState, TBindings>, "credentials"> & {
       credentials?: DefinedNodeCredentialAccessors<TBindings>;
     },
   ): MaybePromise<DefinePollingTriggerPollResult<TItemJson, TState>>;
-  /** Registers the synthesised runtime class with the plugin container. */
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
-// ---------------------------------------------------------------------------
-// DefinedPollingTriggerConfig (TriggerNodeConfig shape for the engine)
-// ---------------------------------------------------------------------------
-
-/**
- * TriggerNodeConfig produced by `DefinedPollingTrigger.create(...)`.
- * Holds user configuration and credential requirements for the engine.
- * The setup state type is opaque `JsonValue | undefined` — the runtime
- * uses an internal wrapped shape that plugin authors never see.
- */
-export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, TItemJson> implements TriggerNodeConfig<
-  TItemJson,
-  JsonValue | undefined
-> {
+export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, TItemJson>
+  implements TriggerNodeConfig<TItemJson, JsonValue | undefined>, PollingTriggerConfig
+{
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown>;
   readonly icon: string | undefined;
@@ -222,6 +119,7 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
     private readonly inspectorSummaryFn?: (
       args: Readonly<{ config: TConfig }>,
     ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined,
+    private readonly defaultPollIntervalMs?: number,
   ) {
     this.type = typeToken;
     this.icon = icon;
@@ -234,16 +132,20 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
     return this.credentialRequirements;
   }
 
+  getTriggerPollConfig(): Readonly<{ config: JsonObject; pollIntervalMs?: number }> {
+    const cfgPollInterval = (this.cfg as Partial<{ pollIntervalMs: number }>).pollIntervalMs;
+    const resolvedInterval = cfgPollInterval ?? this.defaultPollIntervalMs;
+    return {
+      config: this.cfg as unknown as JsonObject,
+      pollIntervalMs: resolvedInterval,
+    };
+  }
+
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     return this.inspectorSummaryFn?.({ config: this.cfg });
   }
 }
 
-// ---------------------------------------------------------------------------
-// Internal wrapped state helpers
-// ---------------------------------------------------------------------------
-
-/** Opaque shape stored in the trigger setup state repository. @internal */
 interface InternalWrappedState {
   readonly userState: JsonValue | undefined;
   readonly seenKeys: ReadonlyArray<string>;
@@ -258,32 +160,6 @@ function isWrappedState(value: unknown): value is InternalWrappedState {
   );
 }
 
-// ---------------------------------------------------------------------------
-// Implementation factory
-// ---------------------------------------------------------------------------
-
-/**
- * Declarative helper for authoring polling triggers.
- *
- * ```ts
- * export const onNewMail = definePollingTrigger({
- *   key: "my-plugin.on-new-mail",
- *   title: "On new mail",
- *   configSchema: z.object({ folder: z.string() }),
- *   credentials: { auth: myOAuthCredentialType },
- *   initialState: () => ({ lastSeenId: undefined }),
- *   pollIntervalMs: 60_000,
- *   async poll({ config, state, credentials }) {
- *     const session = await credentials.auth();
- *     const messages = await fetchMessages(session, config.folder, state.lastSeenId);
- *     return {
- *       items: messages.map(m => ({ json: m, dedupKey: m.id })),
- *       nextState: { lastSeenId: messages[0]?.id ?? state.lastSeenId },
- *     };
- *   },
- * });
- * ```
- */
 export function definePollingTrigger<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -298,10 +174,6 @@ export function definePollingTrigger<
 
   type TConfig_ = DefinedPollingTriggerConfig<TConfig, TItemJson>;
 
-  // ---------------------------------------------------------------------------
-  // Synthesised runtime class (implements TestableTriggerNode)
-  // ---------------------------------------------------------------------------
-
   const DefinedPollingTriggerRuntime = class implements TestableTriggerNode<TConfig_> {
     readonly kind = "trigger" as const;
     readonly outputPorts = ["main"] as const;
@@ -311,7 +183,6 @@ export function definePollingTrigger<
       const intervalMs =
         (cfg as Partial<{ pollIntervalMs: number }>).pollIntervalMs ?? options.pollIntervalMs ?? DEFAULT_INTERVAL_MS;
 
-      // Unwrap previously persisted state, or create the initial wrapped state.
       const persisted = ctx.previousState;
       const existingWrapped: InternalWrappedState | undefined = isWrappedState(persisted) ? persisted : undefined;
       const seedWrapped: InternalWrappedState = existingWrapped ?? {
@@ -337,7 +208,6 @@ export function definePollingTrigger<
             credentials: credentialAccessors,
           });
 
-          // Dedup: filter items whose dedupKey is already seen
           const newItems: Array<{ json: TItemJson }> = [];
           const newKeys: string[] = [];
           for (const item of pollResult.items) {
@@ -350,7 +220,6 @@ export function definePollingTrigger<
             newItems.push({ json: item.json });
           }
 
-          // Merge keys, cap the window at 2000 to bound state size
           const allKeys = [...wrapped.seenKeys, ...newKeys];
           const cappedKeys = allKeys.length > 2000 ? allKeys.slice(allKeys.length - 2000) : allKeys;
 
@@ -384,11 +253,7 @@ export function definePollingTrigger<
     }
   };
 
-  persistedNode({ name: options.key })(DefinedPollingTriggerRuntime);
-
-  // ---------------------------------------------------------------------------
-  // Returned definition object
-  // ---------------------------------------------------------------------------
+  persistedNode({ name: options.key, packageName: options.packageName })(DefinedPollingTriggerRuntime);
 
   const definition: DefinedPollingTrigger<TKey, TConfig, TItemJson, TState, TBindings> = {
     kind: "defined-polling-trigger",
@@ -411,6 +276,7 @@ export function definePollingTrigger<
         options.inspectorSummary as
           | ((args: Readonly<{ config: TConfig }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined)
           | undefined,
+        options.pollIntervalMs,
       );
     },
 

package/src/authoring/definePollingTriggerInternals.ts

@@ -1,7 +1,3 @@
-/**
- * Shared internal helpers for defineNode and definePollingTrigger.
- * Not part of the public API — import only from authoring helpers.
- */
 import type { AnyCredentialType, CredentialRequirement, CredentialTypeId } from "../contracts/credentialTypes";
 import type { NodeExecutionContext } from "../contracts/runtimeTypes";
 import type { RunnableNodeConfig } from "../contracts/workflowTypes";

package/src/authoring/nodeBaseOptions.types.ts

@@ -1,17 +1,3 @@
-/**
- * Core-local copy of the per-instance authoring options every `define*` factory's `create(...)`
- * accepts in its trailing argument: a stable `id` plus a plain-language `description` (the
- * non-technical "what does this step do" line surfaced in the node sidebar).
- *
- * `description` is a first-class option — passed inline exactly like `id` — and is threaded onto
- * the config instance as an OWN ENUMERABLE field so it flows into the persisted workflow snapshot
- * (`WorkflowSnapshotCodec` serializes via `JSON.parse(JSON.stringify(config))`, which only captures
- * own enumerable properties — never a getter).
- *
- * `@codemation/core-nodes` declares an identical `NodeBaseOptions` for its bare-id built-in nodes;
- * core keeps its own copy because core must not depend on `@codemation/core-nodes` (dependency
- * direction). The two types are structurally identical by design.
- */
 export interface NodeBaseOptions {
   readonly id?: string;
   readonly description?: string;

package/src/binaries/boundedReadBinary.types.ts

@@ -2,19 +2,6 @@ import type { BinaryAttachment, BinaryStorage } from "../types";
 import type { BinaryStorageReadResult } from "../types";
 import { BINARY_DEFAULT_MAX_BYTES } from "../contracts/runtimeTypes";
 
-/**
- * Reads all bytes from an already-opened binary stream into a contiguous `Uint8Array`.
- *
- * Safety contract:
- *  - `attachment.size` is checked against `maxBytes` *before* any allocation (no OOM).
- *  - A single buffer of exactly `attachment.size` is pre-allocated; the stream fills it
- *    directly — no chunks array, no doubling.
- *  - A byte-count mismatch between the declared size and actual stream content is an error.
- *
- * This is the single canonical implementation; `ExecutionBinaryService.getBytes`,
- * `getText`, and `getJson` all delegate here. The per-package `readBinaryBody` helpers
- * in `core-nodes` and `core-nodes-ocr` have been removed in favour of this function.
- */
 export async function boundedReadBinary(
   result: BinaryStorageReadResult,
   attachment: BinaryAttachment,
@@ -49,7 +36,6 @@ export async function boundedReadBinary(
   return out;
 }
 
-/** Shared implementation of `getBytes` used by both binary-service classes. */
 export async function readBinaryAsBytes(
   storage: BinaryStorage,
   attachment: BinaryAttachment,
@@ -62,7 +48,6 @@ export async function readBinaryAsBytes(
   return boundedReadBinary(result, attachment, maxBytes);
 }
 
-/** Shared implementation of `getText` used by both binary-service classes. */
 export async function readBinaryAsText(
   storage: BinaryStorage,
   attachment: BinaryAttachment,
@@ -72,7 +57,6 @@ export async function readBinaryAsText(
   return new TextDecoder().decode(bytes);
 }
 
-/** Shared implementation of `getJson` used by both binary-service classes. */
 export async function readBinaryAsJson<T = unknown>(
   storage: BinaryStorage,
   attachment: BinaryAttachment,

package/src/bootstrap/index.ts

@@ -1,4 +1,3 @@
-/** Composition-root engine graph and advanced runtime wiring. Not part of the main `@codemation/core` barrel. */
 export { Engine } from "../orchestration/Engine";
 export {
   AbortControllerFactory,
@@ -57,4 +56,11 @@ export {
   WorkflowStoragePolicyEvaluator,
   type EngineExecutionLimitsPolicyConfig,
 } from "../policies";
-export { MissingRuntimeTriggerToken, PersistedWorkflowTokenRegistry } from "../workflowSnapshots";
+export {
+  MissingRuntimeParityGuard,
+  MissingRuntimeTriggerToken,
+  PersistedWorkflowTokenRegistry,
+  WorkflowParityMismatchError,
+  type MissingRuntimeNodeDetail,
+} from "../workflowSnapshots";
+export { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";