@codemation/core 1.0.1 → 2.0.0

package/src/authoring/definePollingTrigger.types.ts

@@ -0,0 +1,396 @@
+/**
+ * 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,
+  JsonValue,
+  NodeExecutionContext,
+  NodeOutputs,
+  TestableTriggerNode,
+  TriggerNodeConfig,
+  TriggerSetupContext,
+  TriggerTestItemsContext,
+  TypeToken,
+} from "..";
+import type { CredentialJsonRecord, CredentialRequirement } from "../contracts/credentialTypes";
+import type { DefinedNodeCredentialAccessors, DefinedNodeCredentialBindings } from "./defineNode.types";
+import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
+import {
+  definedNodeCredentialRequirementFactory,
+  definedNodeCredentialAccessorFactory,
+} 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,
+  TBindings extends DefinedNodeCredentialBindings | undefined,
+> {
+  readonly config: TConfig;
+  readonly state: TState;
+  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,
+  TItemJson,
+  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 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;
+  /**
+   * 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,
+  TItemJson,
+  TState extends JsonValue | undefined,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> {
+  readonly kind: "defined-polling-trigger";
+  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 id - Optional stable node id.
+   */
+  create(cfg: TConfig, name?: string, id?: string): 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
+> {
+  readonly kind = "trigger" as const;
+  readonly type: TypeToken<unknown>;
+  readonly icon: string | undefined;
+
+  constructor(
+    public readonly name: string,
+    public readonly cfg: TConfig,
+    typeToken: TypeToken<unknown>,
+    icon: string | undefined,
+    private readonly credentialRequirements: ReadonlyArray<CredentialRequirement>,
+    public readonly id?: string,
+  ) {
+    this.type = typeToken;
+    this.icon = icon;
+  }
+
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
+    return this.credentialRequirements;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal wrapped state helpers
+// ---------------------------------------------------------------------------
+
+/** Opaque shape stored in the trigger setup state repository. @internal */
+interface InternalWrappedState {
+  readonly userState: JsonValue | undefined;
+  readonly seenKeys: ReadonlyArray<string>;
+}
+
+function isWrappedState(value: unknown): value is InternalWrappedState {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "seenKeys" in (value as Record<string, unknown>) &&
+    Array.isArray((value as InternalWrappedState).seenKeys)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 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,
+  TItemJson,
+  TState extends JsonValue | undefined,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+>(
+  options: DefinePollingTriggerOptions<TKey, TConfig, TItemJson, TState, TBindings>,
+): DefinedPollingTrigger<TKey, TConfig, TItemJson, TState, TBindings> {
+  const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+  const DEFAULT_INTERVAL_MS = 60_000;
+
+  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;
+
+    async setup(ctx: TriggerSetupContext<TConfig_, JsonValue | undefined>): Promise<JsonValue | undefined> {
+      const cfg = ctx.config.cfg;
+      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 ?? {
+        userState: options.initialState ? options.initialState() : undefined,
+        seenKeys: [],
+      };
+
+      const result = await ctx.polling.start<InternalWrappedState, TItemJson>({
+        intervalMs,
+        seedState: seedWrapped,
+        runCycle: async ({ previousState }) => {
+          const wrapped: InternalWrappedState = previousState ?? seedWrapped;
+          const seenSet = new Set(wrapped.seenKeys);
+
+          const credentialAccessors = definedNodeCredentialAccessorFactory.create(
+            options.credentials,
+            ctx,
+          ) as DefinedNodeCredentialAccessors<TBindings>;
+
+          const pollResult = await options.poll({
+            config: cfg,
+            state: wrapped.userState as TState,
+            credentials: credentialAccessors,
+          });
+
+          // Dedup: filter items whose dedupKey is already seen
+          const newItems: Array<{ json: TItemJson }> = [];
+          const newKeys: string[] = [];
+          for (const item of pollResult.items) {
+            if (item.dedupKey !== undefined) {
+              if (seenSet.has(item.dedupKey)) {
+                continue;
+              }
+              newKeys.push(item.dedupKey);
+            }
+            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;
+
+          const nextWrapped: InternalWrappedState = {
+            userState: pollResult.nextState,
+            seenKeys: cappedKeys,
+          };
+
+          return {
+            items: newItems as Items<TItemJson>,
+            nextState: nextWrapped,
+          };
+        },
+      });
+
+      return result as JsonValue | undefined;
+    }
+
+    async execute(items: Items<TItemJson>, ctx: NodeExecutionContext<TConfig_>): Promise<NodeOutputs> {
+      if (options.execute) {
+        return await options.execute(items, ctx);
+      }
+      return { main: items };
+    }
+
+    async getTestItems(ctx: TriggerTestItemsContext<TConfig_>): Promise<Items> {
+      if (options.testItems) {
+        return await options.testItems(ctx);
+      }
+      return [];
+    }
+  };
+
+  persistedNode({ name: options.key })(DefinedPollingTriggerRuntime);
+
+  // ---------------------------------------------------------------------------
+  // Returned definition object
+  // ---------------------------------------------------------------------------
+
+  const definition: DefinedPollingTrigger<TKey, TConfig, TItemJson, TState, TBindings> = {
+    kind: "defined-polling-trigger",
+    key: options.key,
+    title: options.title,
+    description: options.description,
+
+    create(cfg: TConfig, name = options.title, id?: string): DefinedPollingTriggerConfig<TConfig, TItemJson> {
+      return new DefinedPollingTriggerConfig<TConfig, TItemJson>(
+        name,
+        cfg,
+        DefinedPollingTriggerRuntime,
+        options.icon,
+        credentialRequirements,
+        id,
+      );
+    },
+
+    poll(pollCtx) {
+      return options.poll({
+        config: pollCtx.config,
+        state: pollCtx.state,
+        credentials: (pollCtx.credentials ?? {}) as DefinedNodeCredentialAccessors<TBindings>,
+      });
+    },
+
+    register(context) {
+      context.registerNode(DefinedPollingTriggerRuntime);
+    },
+  };
+
+  return definition;
+}

package/src/authoring/definePollingTriggerInternals.ts

@@ -0,0 +1,74 @@
+/**
+ * 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";
+import type { DefinedNodeCredentialAccessors, DefinedNodeCredentialBindings } from "./defineNode.types";
+
+type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
+
+export const definedNodeCredentialRequirementFactory = {
+  create(bindings: DefinedNodeCredentialBindings | undefined): ReadonlyArray<CredentialRequirement> {
+    if (!bindings) {
+      return [];
+    }
+    return Object.entries(bindings).map(([slotKey, binding]) => {
+      if (typeof binding === "string" || this.isCredentialType(binding)) {
+        return {
+          slotKey,
+          label: this.humanize(slotKey),
+          acceptedTypes: [this.resolveTypeId(binding)],
+        };
+      }
+
+      const types = Array.isArray(binding.type) ? binding.type : [binding.type];
+      return {
+        slotKey,
+        label: binding.label ?? this.humanize(slotKey),
+        acceptedTypes: types.map((entry) => this.resolveTypeId(entry)),
+        optional: binding.optional,
+        helpText: binding.helpText,
+        helpUrl: binding.helpUrl,
+      };
+    });
+  },
+
+  isCredentialType(value: unknown): value is AnyCredentialType {
+    return (
+      Boolean(value) &&
+      typeof value === "object" &&
+      "definition" in (value as Record<string, unknown>) &&
+      typeof (value as AnyCredentialType).definition?.typeId === "string"
+    );
+  },
+
+  resolveTypeId(type: ResolvableCredentialType): string {
+    return typeof type === "string" ? type : type.definition.typeId;
+  },
+
+  humanize(key: string): string {
+    return key
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/[-_.]+/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/^./, (character) => character.toUpperCase());
+  },
+} as const;
+
+export const definedNodeCredentialAccessorFactory = {
+  create<TBindings extends DefinedNodeCredentialBindings | undefined>(
+    bindings: TBindings,
+    ctx:
+      | NodeExecutionContext<RunnableNodeConfig<any, any>>
+      | { getCredential<TSession = unknown>(slotKey: string): Promise<TSession> },
+  ): DefinedNodeCredentialAccessors<TBindings> {
+    if (!bindings) {
+      return {} as DefinedNodeCredentialAccessors<TBindings>;
+    }
+    const entries = Object.keys(bindings).map((slotKey) => [slotKey, () => ctx.getCredential(slotKey)] as const);
+    return Object.fromEntries(entries) as DefinedNodeCredentialAccessors<TBindings>;
+  },
+} as const;

package/src/authoring/index.ts

@@ -14,3 +14,22 @@ export { defineBatchNode, defineNode } from "./defineNode.types";
 export type { DefineCredentialOptions } from "./defineCredential.types";
 export { defineCredential } from "./defineCredential.types";
 export { callableTool } from "./callableTool.types";
+export { DefinedCollectionRegistry } from "./DefinedCollectionRegistry";
+export type {
+  DefinedCollection,
+  CollectionDefinition,
+  CollectionFieldDefinition,
+  CollectionIndexDefinition,
+  CollectionColumnBuilder,
+  DefineCollectionOptions,
+} from "./defineCollection.types";
+export { defineCollection, c } from "./defineCollection.types";
+export type {
+  DefinePollingTriggerOptions,
+  DefinePollingTriggerPollContext,
+  DefinePollingTriggerPollResult,
+  DefinePollingTriggerExecuteContext,
+  DefinePollingTriggerTestItemsContext,
+  DefinedPollingTrigger,
+} from "./definePollingTrigger.types";
+export { definePollingTrigger, DefinedPollingTriggerConfig } from "./definePollingTrigger.types";

package/src/bootstrap/index.ts

@@ -1,5 +1,14 @@
 /** Composition-root engine graph and advanced runtime wiring. Not part of the main `@codemation/core` barrel. */
 export { Engine } from "../orchestration/Engine";
+export {
+  AbortControllerFactory,
+  TestSuiteOrchestrator,
+  TestSuiteRunIdFactory,
+  type RunTestSuiteArgs,
+  type TestSuiteCaseOutcome,
+  type TestSuiteOrchestratorEngine,
+  type TestSuiteRunResult,
+} from "../orchestration";
 export { EngineFactory, type EngineCompositionDeps } from "../runtime/EngineFactory";
 export {
   EngineRuntimeRegistrar,

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -52,7 +52,11 @@ export class EngineRuntimeRegistrar {
       container.registerSingleton(RunnableOutputBehaviorResolver, RunnableOutputBehaviorResolver);
     }
     if (!container.isRegistered(ChildExecutionScopeFactory, true)) {
-      container.registerSingleton(ChildExecutionScopeFactory, ChildExecutionScopeFactory);
+      container.register(ChildExecutionScopeFactory, {
+        useFactory: instanceCachingFactory((dependencyContainer) => {
+          return new ChildExecutionScopeFactory(dependencyContainer.resolve(CoreTokens.ActivationIdFactory));
+        }),
+      });
     }
     container.registerSingleton(EngineExecutionLimitsPolicyFactory, EngineExecutionLimitsPolicyFactory);
     container.registerSingleton(NodeInstanceFactoryFactory, NodeInstanceFactoryFactory);

package/src/contracts/assertionTypes.ts

@@ -0,0 +1,63 @@
+import type { JsonValue, NodeId } from "./workflowTypes";
+
+/**
+ * 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`.
+ */
+export 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>>;
+}
+
+/**
+ * Default {@link AssertionResult.passThreshold} when authors omit it. Boolean-style assertions
+ * (assertEqual / contains / etc.) emit `score: 1` or `score: 0` so this default works for them;
+ * AI-judge assertions are expected to set their own threshold.
+ */
+export const DEFAULT_ASSERTION_PASS_THRESHOLD = 0.5;
+
+/**
+ * Derive whether an assertion result is considered "passing" using the score-based contract:
+ * `errored` always fails, otherwise `score >= (passThreshold ?? 0.5)`. This is the canonical
+ * derivation — UI and rollup code should call it rather than inlining the comparison so future
+ * tweaks (e.g. NaN handling) land in one place.
+ */
+export function deriveAssertionPassed(result: {
+  readonly score: number;
+  readonly passThreshold?: number;
+  readonly errored?: true;
+}): boolean {
+  if (result.errored === true) return false;
+  const threshold = result.passThreshold ?? DEFAULT_ASSERTION_PASS_THRESHOLD;
+  return result.score >= threshold;
+}
+
+/**
+ * Provenance for a persisted {@link AssertionResult}: which node produced it and where in the
+ * per-item iteration tree it landed. Filled in by the host-side persister, not the node itself.
+ */
+export interface AssertionResultProvenance {
+  readonly nodeId: NodeId;
+  /** Per-item iteration id when the emitting node ran inside a per-item loop. */
+  readonly iterationId?: string;
+  /** Item index (0-based) within the activation that produced this assertion. */
+  readonly itemIndex?: number;
+}

package/src/contracts/baseTypes.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal base types that have no dependencies on other contracts.
+ * Used by credentialTypes, workflowTypes, and other contract layers
+ * to avoid circular dependencies.
+ */
+
+export type WorkflowId = string;
+export type NodeId = string;
+export type OutputPortKey = string;
+export type InputPortKey = string;
+export type PersistedTokenId = string;
+export type NodeConnectionName = string;

package/src/contracts/collectionTypes.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
+ */
+export 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.
+ */
+export type CollectionsContext = Readonly<Record<string, CollectionStore>>;

package/src/contracts/credentialTypes.ts

@@ -1,4 +1,4 @@
-import type { NodeId, WorkflowId } from "./workflowTypes";
+import type { NodeId, WorkflowId } from "./baseTypes";
 
 export type CredentialTypeId = string;
 export type CredentialInstanceId = string;
@@ -91,6 +91,28 @@ export type CredentialOAuth2AuthDefinition = Readonly<
       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;
+    }
 >;
 
 export type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;