@codemation/core 0.13.2 → 0.15.0

package/src/contracts/telemetryTypes.ts

@@ -73,13 +73,6 @@ export 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;
 }
 

package/src/contracts/testTriggerTypes.ts

@@ -1,18 +1,8 @@
 import type { Item, NodeId, WorkflowId } from "./workflowTypes";
 import type { TriggerNodeConfig } from "./workflowTypes";
 
-/**
- * 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`.
- */
 export 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.
- */
 export interface TestTriggerSetupContext<
   TConfig extends TestTriggerNodeConfig<unknown> = TestTriggerNodeConfig<unknown>,
 > {
@@ -20,47 +10,14 @@ export interface TestTriggerSetupContext<
   readonly nodeId: NodeId;
   readonly config: TConfig;
   readonly testSuiteRunId: TestSuiteRunId;
-  /**
-   * 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}.
-   */
   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.
- */
 export interface TestTriggerNodeConfig<TOutputJson = unknown> extends TriggerNodeConfig<TOutputJson, undefined> {
   readonly triggerKind: "test";
-  /**
-   * 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).
-   */
   generateItems(ctx: TestTriggerSetupContext<TestTriggerNodeConfig<TOutputJson>>): AsyncIterable<Item<TOutputJson>>;
-  /** Per-suite-run cap on simultaneously-executing test cases. Default: 4. */
   readonly concurrency?: number;
-  /**
-   * 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."`
-   */
   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>): string | undefined;
 }

package/src/contracts/triggerInvokerTypes.ts

@@ -0,0 +1,6 @@
+import type { Items, TriggerNodeConfig } from "./workflowTypes";
+import type { TriggerInstanceId } from "./webhookTypes";
+
+export interface TriggerInvoker {
+  invoke(trigger: TriggerInstanceId, config: TriggerNodeConfig, lastRanAt: string | undefined): Promise<Items>;
+}

package/src/contracts/webhookTypes.ts

@@ -11,7 +11,6 @@ export interface WebhookControlSignal {
 
 export interface WebhookTriggerRoutingDiagnostics {
   warn(message: string): void;
-  /** Inactive workflows omitted from the webhook route index (optional; host should wire for clarity at boot/reload). */
   info?(message: string): void;
 }
 
@@ -20,9 +19,7 @@ export interface TriggerInstanceId {
   nodeId: NodeId;
 }
 
-/** Match for an incoming HTTP request: user-defined URL segment + workflow trigger node. */
 export interface WebhookInvocationMatch {
-  /** Same value as the webhook trigger's configured endpoint key (URL segment under the webhook base path). */
   endpointPath: string;
   workflowId: WorkflowId;
   nodeId: NodeId;
@@ -30,20 +27,15 @@ export interface WebhookInvocationMatch {
   parseJsonBody?: (body: unknown) => unknown;
 }
 
-/** Result of resolving an HTTP method + endpoint path against the catalog webhook index (404 vs 405 vs match). */
 export type WebhookTriggerResolution =
   | { status: "notFound" }
   | { status: "methodNotAllowed"; match: WebhookInvocationMatch }
   | { status: "ok"; match: WebhookInvocationMatch };
 
-/**
- * Resolves webhook routes from workflow definitions (catalog-backed index, no registration at trigger setup).
- */
 export interface WebhookTriggerMatcher {
   match(args: { endpointPath: string; method: HttpMethod }): WebhookInvocationMatch | undefined;
   lookup(endpointPath: string): WebhookInvocationMatch | undefined;
   onEngineWorkflowsLoaded?(): void;
   onEngineStopped?(): void;
-  /** Rebuild route index after activation changes without stopping the engine. */
   reloadWebhookRoutes?(): void;
 }

package/src/contracts/workflowActivationPolicy.ts

@@ -1,14 +1,9 @@
 import type { WorkflowId } from "./workflowTypes";
 
-/**
- * Host-controlled policy: when false, trigger {@link TriggerNode} setup is skipped and webhook routes
- * for that workflow are not registered (see engine trigger runtime + webhook matcher).
- */
 export interface WorkflowActivationPolicy {
   isActive(workflowId: WorkflowId): boolean;
 }
 
-/** Default for tests and harnesses: every workflow is treated as active (legacy behavior). */
 export class AllWorkflowsActiveWorkflowActivationPolicy implements WorkflowActivationPolicy {
   isActive(_workflowId: WorkflowId): boolean {
     return true;

package/src/contracts/workflowTypes.ts

@@ -23,7 +23,6 @@ export interface JsonObject {
 }
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 export type JsonArray = ReadonlyArray<JsonValue>;
-/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
 export type JsonNonArray = JsonPrimitive | JsonObject;
 
 export interface Edge {
@@ -31,11 +30,6 @@ export interface Edge {
   to: { nodeId: NodeId; input: InputPortKey };
 }
 
-/**
- * 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.
- */
 export interface WorkflowNodeConnection {
   readonly parentNodeId: NodeId;
   readonly connectionName: NodeConnectionName;
@@ -47,18 +41,10 @@ export interface WorkflowDefinition {
   name: string;
   nodes: NodeDefinition[];
   edges: Edge[];
-  /**
-   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
-   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
-   */
   readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
-  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
   discoveryPathSegments?: readonly string[];
-  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
   readonly prunePolicy?: WorkflowPrunePolicySpec;
-  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
   readonly storagePolicy?: WorkflowStoragePolicySpec;
-  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
   readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
 }
 
@@ -76,50 +62,22 @@ export interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
+  readonly description?: string;
   readonly execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
-  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
   readonly retryPolicy?: RetryPolicySpec;
-  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
-  /**
-   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
-   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
-   * main batches skip downstream execution and propagate the empty path.
-   */
   readonly continueWhenEmptyOutput?: boolean;
-  /**
-   * Declared I/O port names for canvas authoring (unioned with ports inferred from edges).
-   * Use for dynamic routers (Switch) and future error ports.
-   */
   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;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — the design-time
-   * "what does this node do" panel that renders before any run telemetry exists.
-   *
-   * Return 2–6 short label/value pairs derived from this config (method + url for an HTTP
-   * call, model + tool list for an agent, schedule + timezone for a cron trigger, etc.).
-   * Values are truncated by the UI; aim for one line each. Return `undefined` to opt out
-   * — the inspector hides the section when no rows are produced.
-   *
-   * Implement on the config class instance so the function can read sibling config fields.
-   * `defineNode({ inspectorSummary })` plumbs through to this.
-   */
   inspectorSummary?(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 
-/**
- * One row of a node's static configuration summary. See {@link NodeConfigBase.inspectorSummary}.
- */
+export interface PollingTriggerConfig {
+  getTriggerPollConfig(): Readonly<{ config: JsonObject; pollIntervalMs?: number }>;
+}
+
 export interface NodeInspectorSummaryRow {
   readonly label: string;
   readonly value: string;
@@ -129,24 +87,11 @@ export declare const runnableNodeInputType: unique symbol;
 export declare const runnableNodeOutputType: unique symbol;
 export declare const triggerNodeOutputType: unique symbol;
 
-/**
- * Runnable node: **`TInputJson`** is what **`inputSchema`** validates on **`item.json`** (the wire payload).
- * **`TOutputJson`** is emitted `item.json` on outputs.
- */
 export interface RunnableNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson;
   readonly [runnableNodeOutputType]?: TOutputJson;
-  /**
-   * Optional Zod input contract for {@link RunnableNode} when not set on the node class.
-   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
-   */
   readonly inputSchema?: ZodType<TInputJson>;
-  /**
-   * When an activation receives **zero** input items, the engine normally runs `execute` zero times.
-   * Set to **`runOnce`** to run `execute` once with an empty `items` batch (and a synthetic wire item for schema parsing).
-   * Used by batch-style callback nodes (built-in `Callback`) so `callback([], ctx)` still runs.
-   */
   readonly emptyBatchExecution?: "skip" | "runOnce";
 }
 
@@ -159,11 +104,6 @@ export interface TriggerNodeConfig<
   readonly kind: "trigger";
   readonly [triggerNodeOutputType]?: TOutputJson;
   readonly [triggerNodeSetupStateType]?: TSetupState;
-  /**
-   * 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";
 }
 
@@ -232,28 +172,15 @@ export type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 
 export type RunId = string;
 export 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.
- */
 export type NodeIterationId = string;
 
 export interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
-  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
   subworkflowDepth?: number;
-  /** Effective max node activations from the parent run (propagated to child policy merge). */
   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?: import("./runTypes").RunTestContext;
 }
 
@@ -298,7 +225,6 @@ export interface NodeOffloadPolicy {
   decide(args: { workflowId: WorkflowId; nodeId: NodeId; config: NodeConfigBase }): NodeSchedulerDecision;
 }
 
-/** Whether to persist run execution data after the workflow finishes. */
 export type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
 
 export type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
@@ -363,7 +289,6 @@ export interface NodeErrorHandler {
 
 export type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 
-/** Runtime defaults when workflow omits prune/storage fields (typically from host env). */
 export interface WorkflowPolicyRuntimeDefaults {
   readonly retentionSeconds?: number;
   readonly binaryRetentionSeconds?: number;

package/src/contracts/workspaceFileTypes.ts

@@ -1,62 +1,26 @@
 import type { TypeToken } from "../di";
 
-/**
- * Metadata returned for a workspace file object.
- * Filename and contentType come from the S3 object's custom metadata
- * (stamped by the control plane at upload time — story 03).
- * The local-fs driver reads them from a companion .meta.json sidecar.
- */
 export interface WorkspaceFileMetadata {
-  /** Storage key: `<workspaceId>/files/<fileId>` */
   readonly key: string;
-  /** Last path segment of the storage key. */
   readonly fileId: string;
-  /** Original filename as stamped by the CP at upload time. Empty string if not yet stamped (pre-story-03). */
   readonly filename: string;
   readonly contentType: string;
   readonly size: number;
   readonly lastModified: Date;
 }
 
-/**
- * Read-only, workspace-scoped port for accessing the shared workspace file pool.
- * Implemented in `@codemation/host`; nodes reach it via `ctx.resolve(WorkspaceFileStorageToken)`.
- *
- * Key scheme: `<workspaceId>/files/<fileId>` — but nodes never construct raw keys.
- * Use the workspace-level helpers (`listFiles`, `getFileByName`, `getFileById`) instead.
- *
- * This adapter is SEPARATE from the run-scoped BinaryStorage — do not confuse the two.
- */
 export interface IWorkspaceFileStorage {
-  /**
-   * Lists all files in this workspace, sorted newest-first by lastModified.
-   * Optional case-insensitive substring filter on filename.
-   */
   listFiles(filenameFilter?: string): Promise<ReadonlyArray<WorkspaceFileMetadata>>;
 
-  /**
-   * Returns metadata for the newest file with the given filename in this workspace.
-   * @throws WorkspaceFileNotFoundError when no file with that name exists.
-   */
   getFileByName(filename: string): Promise<WorkspaceFileMetadata>;
 
-  /**
-   * Returns metadata for the file with the given fileId in this workspace.
-   * @throws WorkspaceFileNotFoundError when no file with that id exists.
-   */
   getFileById(fileId: string): Promise<WorkspaceFileMetadata>;
 
-  /**
-   * Returns a non-buffered stream of the stored object's bytes.
-   * Accepts a full storage key or a fileId (prefixes as needed).
-   * @throws WorkspaceFileNotFoundError when the key does not exist.
-   */
   getStream(key: string): Promise<ReadableStream<Uint8Array>>;
+
+  writeFile(filename: string, body: Uint8Array, contentType: string): Promise<WorkspaceFileMetadata>;
 }
 
-/**
- * Error thrown when a requested workspace file key does not exist.
- */
 export class WorkspaceFileNotFoundError extends Error {
   constructor(readonly key: string) {
     super(`Workspace file not found: ${key}`);
@@ -64,10 +28,14 @@ export class WorkspaceFileNotFoundError extends Error {
   }
 }
 
-/**
- * DI token for the workspace-scoped file storage adapter.
- * Registered by `@codemation/host`; resolved by workspace-file nodes via `ctx.resolve(...)`.
- */
+export interface IWorkspaceFileRegistrar {
+  register(meta: WorkspaceFileMetadata): Promise<void>;
+}
+
 export const WorkspaceFileStorageToken = Symbol.for("codemation.core.WorkspaceFileStorage") as TypeToken<
   IWorkspaceFileStorage | undefined
 >;
+
+export const WorkspaceFileRegistrarToken = Symbol.for("codemation.core.WorkspaceFileRegistrar") as TypeToken<
+  IWorkspaceFileRegistrar | undefined
+>;

package/src/contracts.ts

@@ -1,28 +1,23 @@
-// Pure-type-only re-exports. Use this for type-only consumers that should not drag in runtime DSL or factory code.
-// This subpath prevents unnecessary compile-graph bloat for packages that only need types like NodeId, Items, etc.
-
 export type * from "./contracts/agentMcpTypes";
+export type { WorkspaceId, DispatchItemMeta, WorkflowDispatch } from "./contracts/dispatchTypes";
+export { serializeDispatch, deserializeDispatch } from "./contracts/dispatchTypes";
 export * from "./contracts/AgentBindError";
 export * from "./contracts/NoOpAgentMcpIntegration";
 export type * from "./contracts/baseTypes";
 export type * from "./contracts/assertionTypes";
-// assertionTypes also exports a runtime helper for deriving pass/fail from a score+threshold.
-// We keep the type-only re-export above and surface the helper explicitly here so UI consumers
-// (next-host) don't need to re-implement the comparison.
 export { deriveAssertionPassed, DEFAULT_ASSERTION_PASS_THRESHOLD } from "./contracts/assertionTypes";
 export type * from "./contracts/params";
 export type * from "./contracts/retryPolicySpec.types";
 export type * from "./contracts/CostCatalogContract";
 export type * from "./contracts/executionPersistenceContracts";
 export type * from "./contracts/runtimeTypes";
+export type * from "./contracts/triggerInvokerTypes";
 export type * from "./contracts/telemetryTypes";
 export type * from "./contracts/testTriggerTypes";
 export type * from "./contracts/runTypes";
 export type * from "./contracts/webhookTypes";
 export type * from "./contracts/workflowTypes";
 
-// credentialTypes mixes types (Credential* interfaces) with runtime (CredentialUnboundError class).
-// Export type-only subset for pure type consumers.
 export type {
   CredentialTypeId,
   CredentialInstanceId,
@@ -44,6 +39,8 @@ export type {
   CredentialInstanceRecord,
   CredentialSessionFactoryArgs,
   CredentialSessionFactory,
+  CredentialAccessTokenSessionArgs,
+  CredentialAccessTokenSessionFactory,
   CredentialHealthTester,
   CredentialType,
   AnyCredentialType,
@@ -51,8 +48,6 @@ export type {
   CredentialTypeRegistry,
 } from "./contracts/credentialTypes";
 
-// CostTrackingTelemetryContract mixes types with const runtime values (metric/attribute names).
-// Export type-only subset for pure type consumers.
 export type {
   CostTrackingComponent,
   CostTrackingUsageRecord,
@@ -60,3 +55,16 @@ export type {
   CostTrackingTelemetry,
   CostTrackingTelemetryFactory,
 } from "./contracts/CostTrackingTelemetryContract";
+
+export type {
+  DeploymentManifestSchemaVersion,
+  ManifestTriggerConfig,
+  ManifestNodeCredentialShape,
+  WorkflowDeploymentManifest,
+} from "./contracts/deploymentManifestTypes";
+export {
+  DEPLOYMENT_MANIFEST_SCHEMA_VERSION,
+  serializeManifest,
+  deserializeManifest,
+  emitWorkflowManifest,
+} from "./contracts/deploymentManifestTypes";

package/src/credentials/CredentialMaterialProvider.types.ts

@@ -1,35 +1,12 @@
 import type { OAuthMaterial } from "./OAuthFlowExecutor.types";
 
-/**
- * Material provider seam — see `docs/design/credentials-oauth-unification.md`,
- * "Material provider seam" section. Sits beside the workspace's
- * `CredentialStore`; persistence of the row stays at the store, persistence of
- * the bytes goes through this provider so they can live at the control plane
- * in managed mode.
- */
-
-/**
- * Pointer to material bytes. For local rows `ref` is the workspace instance id
- * and the bytes co-locate with the row (existing `CredentialOAuth2Material` /
- * `CredentialSecretMaterial` tables). For control-plane rows `ref` is the
- * CP-side credential id; the workspace stores only the pointer.
- */
 export type CredentialMaterialRef = Readonly<{
   source: "local" | "control-plane";
   id: string;
 }>;
 
-/**
- * Decrypted material bytes returned by a provider. Shape matches
- * `OAuthMaterial` — every supported credential type today is OAuth-shaped.
- */
 export type MaterialBundle = OAuthMaterial;
 
-/**
- * Caller context recorded by the CP material endpoint per fetch (D5 in the
- * `credentials-vault` sprint README). The local provider accepts but ignores
- * it; standalone mode has no audit log.
- */
 export type CallerContext = Readonly<{
   workspaceId: string;
   caller:
@@ -45,11 +22,6 @@ export interface CredentialMaterialProvider {
   setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void>;
 }
 
-/**
- * Thrown by a provider when asked to operate on a `ref.source` it does not
- * handle (e.g. the local provider being asked to read `control-plane` bytes).
- * Exported so `instanceof`-checks work across the workspace boundary.
- */
 export class IllegalMaterialSourceError extends Error {
   constructor(
     public readonly source: CredentialMaterialRef["source"],

package/src/credentials/ManagedCredentialMaterialWriteError.ts

@@ -1,9 +1,3 @@
-/**
- * Thrown by managed-mode providers when `setMaterial` is called. Managed
- * credential bytes are owned by the control plane; the workspace must not
- * mutate them. See `docs/design/credentials-oauth-unification.md` and
- * `planning/sprints/credentials-vault/02-controlplane-material-provider.md`.
- */
 export class ManagedCredentialMaterialWriteError extends Error {
   constructor(
     message: string = "managed credentials are owned by the control plane; use the Connected apps page to create or modify them.",

package/src/credentials/ManagedMaterialFetchError.ts

@@ -1,9 +1,3 @@
-/**
- * Thrown by `ControlPlaneCredentialMaterialProvider` when the control-plane
- * material endpoint returns a non-2xx response or a malformed body. Exposes
- * the HTTP status and the raw error body so call sites can surface actionable
- * detail without parsing strings.
- */
 export class ManagedMaterialFetchError extends Error {
   constructor(
     public readonly status: number,

package/src/credentials/OAuthFlowExecutor.types.ts

@@ -1,13 +1,3 @@
-/**
- * Four-concept model for credentials (see docs/design/credentials-oauth-unification.md):
- *   1. CredentialType — schema for stored material (e.g. "oauth.google.gmail").
- *   2. Credential slot requirement — which types a node or MCP server accepts.
- *   3. CredentialInstance — a stored, usable token row in the host's credential store.
- *   4. OAuthFlowExecutor (this file) — the only concept that differs between deployment
- *      modes. DI selects one implementation at boot; the rest of the system programs
- *      against this interface alone.
- */
-
 export interface OAuthFlowStartArgs {
   readonly typeId: string;
   readonly scopes: ReadonlyArray<string>;
@@ -34,11 +24,6 @@ export interface OAuthMaterial {
 
 export interface OAuthFlowExecutor {
   start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult>;
-  /**
-   * Returns the instanceId associated with a pending stateToken without consuming it.
-   * Used by callback routes to identify the target instance before calling completeCallback.
-   * Returns undefined when the stateToken is unknown or already consumed.
-   */
   lookupInstanceId(stateToken: string): string | undefined;
   completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial>;
   refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial>;

package/src/di/CoreTokens.ts

@@ -21,6 +21,7 @@ import type {
   WorkflowRepository,
   WorkflowRunnerService,
 } from "../types";
+import type { TriggerInvoker } from "../contracts/triggerInvokerTypes";
 
 export const CoreTokens = {
   PersistedWorkflowTokenRegistry: Symbol.for(
@@ -51,17 +52,12 @@ export const CoreTokens = {
   RunEventBus: Symbol.for("codemation.core.RunEventBus") as TypeToken<RunEventBus>,
   BinaryStorage: Symbol.for("codemation.core.BinaryStorage") as TypeToken<BinaryStorage>,
   WebhookBasePath: Symbol.for("codemation.core.WebhookBasePath") as TypeToken<string>,
-  /** Engine execution limits (defaults + optional host overrides). Consumers may bind a custom instance to override. */
   EngineExecutionLimitsPolicy: Symbol.for(
     "codemation.core.EngineExecutionLimitsPolicy",
   ) as TypeToken<EngineExecutionLimitsPolicy>,
   WorkflowActivationPolicy: Symbol.for(
     "codemation.core.WorkflowActivationPolicy",
   ) as TypeToken<WorkflowActivationPolicy>,
-  /**
-   * Optional. When registered, AIAgentNode uses it to resolve mcpServers bindings,
-   * validate scopes, open pool connections, and prepare the MCP ToolSet map.
-   * Not registered in the default core bootstrap — the host provides the implementation.
-   */
   AgentMcpIntegration: Symbol.for("codemation.core.AgentMcpIntegration") as TypeToken<AgentMcpIntegration>,
+  TriggerInvoker: Symbol.for("codemation.core.TriggerInvoker") as TypeToken<TriggerInvoker>,
 } as const;

package/src/events/ConnectionInvocationEventPublisher.ts

@@ -2,13 +2,6 @@ import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { ParentExecutionRef } from "../types";
 import type { RunEventBus } from "./runEvents";
 
-/**
- * Publishes per-invocation lifecycle records onto the run {@link RunEventBus}.
- *
- * Surgical, per-invocation events let the UI update the right-side inspector
- * timeline as each LLM round / tool call transitions through `running` → `completed`
- * (or `failed`) without depending on a coarse `runSaved` poll.
- */
 export class ConnectionInvocationEventPublisher {
   constructor(
     private readonly eventBus: RunEventBus | undefined,

package/src/events/NodeEventPublisher.ts

@@ -1,7 +1,6 @@
 import type { RunEventBus } from "./runEvents";
 import type { NodeExecutionSnapshot } from "../types";
 
-/** Publishes node lifecycle snapshots onto the run {@link RunEventBus}. */
 export class NodeEventPublisher {
   constructor(private readonly eventBus: RunEventBus | undefined) {}
 

package/src/events/runEvents.ts

@@ -2,15 +2,7 @@ import type { TestSuiteRunId } from "../contracts/testTriggerTypes";
 import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { NodeExecutionSnapshot, ParentExecutionRef, PersistedRunState, RunId, WorkflowId } from "../types";
 
-/**
- * Outcome of a single test case (one workflow run dispatched by the test-suite orchestrator).
- * - `running`: workflow still in flight
- * - `succeeded`: workflow completed AND all assertions passed (or no assertions)
- * - `failed`: workflow failed OR (workflow completed but ≥1 assertion failed)
- * - `errored` / `cancelled`: workflow itself errored or was cancelled
- */
 export type TestCaseRunStatus = "running" | "succeeded" | "failed" | "errored" | "cancelled";
-/** Aggregate outcome of a TestSuiteRun. */
 export type TestSuiteRunStatus = "succeeded" | "failed" | "partial" | "errored" | "cancelled";
 
 export type RunEvent =

package/src/execution/ActivationEnqueueService.ts

@@ -47,15 +47,7 @@ export type ActivationEnqueueRequest = {
   planner: RunQueuePlanner;
   engineCounters?: EngineRunCounters;
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
-  /**
-   * Remaining suspension entries after consuming one for a HITL resume.
-   * When provided, saved alongside the new pending state so they survive the enqueue.
-   */
   suspension?: ReadonlyArray<PersistedSuspensionEntry>;
-  /**
-   * Resume context to attach to the re-activated node's execution context.
-   * Written here and consumed by `NodeExecutionRequestHandlerService` when building ctx.
-   */
   pendingResume?: PendingResumeEntry;
 };
 
@@ -126,8 +118,6 @@ export class ActivationEnqueueService {
         ...args.previousNodeSnapshotsByNodeId,
         [args.request.nodeId]: queuedSnapshot,
       },
-      // HITL: preserve suspension entries and resume context when re-activating a
-      // suspended node. Omit fields when not provided (avoids polluting normal enqueue).
       ...(args.suspension !== undefined ? { suspension: args.suspension } : {}),
       ...(args.pendingResume !== undefined ? { pendingResume: args.pendingResume } : {}),
     });