@blokjs/runner 0.4.0 → 0.6.0

package/dist/tracing/types.d.ts

@@ -161,6 +161,39 @@ export interface WorkflowRun {
      * encountered a wait step (preserves existing semantics).
      */
     lastCompletedStepIndex?: number;
+    /**
+     * v0.6 prerequisite for wait-inside-primitives Phase 2.
+     *
+     * JSON-serialized snapshot of `ctx.state` taken immediately before
+     * `RunnerSteps` throws `WaitDispatchRequest`. On `dispatchDeferred`
+     * re-entry — including the cross-process recovery path where the
+     * scheduler re-builds a fresh ctx from the persisted dispatch row —
+     * `TriggerBase.run` rehydrates `ctx.state` (and its `ctx.vars`
+     * alias) from this column so subsequent steps see the same
+     * pre-wait state regardless of process restart.
+     *
+     * Without this column, only the in-process timer-fire path would
+     * preserve state (state still lives on the original ctx). The
+     * cross-process path would resume with empty `ctx.state`, breaking
+     * Phase 2's iteration-state-persistence promise (a forEach
+     * iteration whose body fired the wait would lose its index, the
+     * loop's accumulator, etc.).
+     *
+     * Capped by `BLOK_STATE_SNAPSHOT_MAX_BYTES` (default 1MB,
+     * matching `BLOK_DISPATCH_PAYLOAD_MAX_BYTES`) — when the
+     * serialized state exceeds the cap, the runner logs a warning and
+     * skips the snapshot (the wait still defers; resumption is
+     * best-effort). Authors can opt out entirely via
+     * `BLOK_STATE_SNAPSHOT_DISABLED=1`. Sensitive keys aren't filtered
+     * here — the snapshot only persists what the workflow has already
+     * computed into `state`, so apply your own redaction in nodes that
+     * write secrets there.
+     *
+     * Undefined for runs that never threw `WaitDispatchRequest`, which
+     * is the vast majority. Persisted column is `state_snapshot`
+     * (sqlite migration v11).
+     */
+    stateSnapshot?: string;
 }
 export type NodeRunStatus = "pending" | "running" | "completed" | "failed" | "skipped";
 export interface NodeRun {
@@ -251,6 +284,24 @@ export interface NodeRun {
      * visible to Studio without recomputing from outputs heuristics.
      */
     wait?: boolean;
+    /**
+     * G2 (v0.6) sub-workflow dispatch strategy — only set for
+     * `nodeType === "subworkflow"`. Mirrors the step config's `dispatch`
+     * field so Studio can distinguish in-process invocations from HTTP
+     * self-call dispatches at a glance.
+     *
+     * - `"in-process"` (default; also represented by `undefined` on legacy
+     *   traces) — child runs in the same Node process via the in-process
+     *   `Runner`.
+     * - `"http-self"` — child is dispatched as a fresh HTTP request to
+     *   `BLOK_SELF_BASE_URL`, potentially landing on a different process
+     *   in a horizontally-scaled deployment.
+     *
+     * Captured at `tracker.startNode()` time alongside `wait` so the rail
+     * badge can compose them (`↳ async` orange + `http` sky for an
+     * async http-self dispatch).
+     */
+    dispatch?: "in-process" | "http-self";
     /**
      * PR 5 E3 — sub-workflow nesting depth surfaced for Studio.
      *
@@ -263,6 +314,138 @@ export interface NodeRun {
      * keep top-level invocations un-cluttered.
      */
     subworkflowDepth?: number;
+    /**
+     * v0.5 — origin middleware name when the trigger's
+     * `runMiddlewareChain` produced this NodeRun. The trigger sets a
+     * `_blokMiddlewareName` sentinel on ctx before dispatching each
+     * middleware; RunnerSteps reads it and propagates here so Studio's
+     * StepRail can surface a `mw:<name>` badge on the inner steps a
+     * middleware produced (otherwise indistinguishable from regular
+     * depth-1 nested steps).
+     */
+    middleware?: string;
+    /**
+     * v0.5.3 — iteration index for steps inside a `forEach` or `loop`
+     * primitive. Set per-iteration by ForEachNode / LoopNode on the
+     * cloned child ctx (`_blokIterationIndex` sentinel); RunnerSteps
+     * reads it and propagates here. Studio's StepRail groups consecutive
+     * sibling rows that share an iterationIndex into a collapsible
+     * "iteration N" header so a 5-iteration forEach with 3 inner steps
+     * renders as 5 grouped sections instead of 15 flat rows with
+     * duplicate names. Undefined for top-level steps, for steps inside
+     * non-iteration primitives (`tryCatch`, `switch`), and for legacy
+     * traces written before v0.5.3.
+     */
+    iterationIndex?: number;
+    /**
+     * v0.6 wait-inside-primitives — iteration cursor. Set on a primitive
+     * iterator's NodeRun (e.g. forEach, loop) by RunnerSteps when an
+     * INNER step throws `WaitDispatchRequest` mid-iteration. Read by
+     * `TriggerBase.run` on dispatchDeferred re-entry and stamped onto
+     * `ctx._blokIterationResume` so the primitive can pick it up.
+     * Persisted column is `iteration_context` (sqlite migration v12).
+     *
+     * Two encodings via a `mode` discriminator:
+     *
+     *   - `mode: "sequential"` (or omitted for back-compat): the Phase 2
+     *     sequential forEach + wait cursor (also reused by Phase 3 loop).
+     *     Records the in-flight iteration index, the inner step index
+     *     where the wait fired, and an in-order `completedResults`
+     *     accumulator covering iterations `[0..iteration-1]`. ForEachNode
+     *     and LoopNode read this on resume to skip the completed prefix.
+     *
+     *   - `mode: "parallel"` (PR follow-up to Phase 3): the parallel
+     *     forEach + wait cursor. Records which iteration's wait fired
+     *     (`waitFiringIteration`), where inside its body
+     *     (`innerStepIndex`), a SPARSE `completedResults` array (slot `i`
+     *     populated iff iteration `i` finished before the wait fired —
+     *     `null` for "ran but returned undefined", JSON-undefined hole
+     *     for "not present"), and the explicit `cancelledIterations`
+     *     list (in-flight + queued indices that need re-launch on
+     *     resume). See `docs/c/devtools/parallel-foreach-wait-spec.mdx`
+     *     for the full contract.
+     *
+     * Undefined on regular NodeRuns and on primitives that completed
+     * without ever throwing a wait.
+     */
+    iterationContext?: IterationContext;
+}
+/**
+ * Discriminated union for the iteration cursor persisted into
+ * `node_runs.iteration_context`. See `NodeRun.iterationContext` for
+ * field-level semantics. The runtime selection lives in:
+ *
+ *   - Write side: `core/runner/src/RunnerSteps.ts` wait-throw site
+ *     (sequential) and `ForEachNode.run` parallel-branch error handler
+ *     (parallel).
+ *   - Read side: `TriggerBase.run` rehydrate stamps the cursor onto
+ *     `ctx._blokIterationResume`; the primitive itself (ForEachNode,
+ *     LoopNode) dispatches on `mode` to the right resume path.
+ */
+export type IterationContext = SequentialIterationContext | ParallelIterationContext | SwitchIterationContext;
+/**
+ * Sequential forEach + wait OR loop + wait cursor. The pre-existing
+ * Phase 2/3 shape — `mode` is optional and defaults to "sequential" on
+ * read so cursors written before the discriminator landed (i.e., main
+ * before this PR) keep being interpreted correctly.
+ */
+export interface SequentialIterationContext {
+    mode?: "sequential";
+    /** Iteration index (0-based) the wait fired in. */
+    iteration: number;
+    /** Inner step index within iteration's body where the wait fired. */
+    innerStepIndex: number;
+    /** Accumulator for iterations [0..iteration-1]; pre-populates `results[]` on resume. */
+    completedResults: unknown[];
+}
+/**
+ * v0.6 Phase 4 — switch + wait cursor. Records which case arm matched
+ * (so on re-entry SwitchNode walks back into the same arm) plus the
+ * inner step within that arm where the wait fired.
+ *
+ * `caseIndex` semantics:
+ *   - `>= 0` — index into the workflow's `cases[]` array.
+ *   - `-1`   — the `default` arm matched.
+ *
+ * `completedResults` is unused for switch (it doesn't iterate) but the
+ * field is kept on the IterationContext union for cross-schema parity.
+ * Always `[]` on switch.
+ */
+export interface SwitchIterationContext {
+    mode: "switch";
+    /** Resolved case index; `-1` denotes the `default` arm. */
+    caseIndex: number;
+    /** Inner step index within the matched arm where the wait fired. */
+    innerStepIndex: number;
+    /** Unused for switch; preserved at schema level for parity. Always `[]`. */
+    completedResults: never[];
+}
+/**
+ * Parallel forEach + wait cursor. The headline contract: persist
+ * completed iteration results, retry incomplete ones on resume. See
+ * `docs/c/devtools/parallel-foreach-wait-spec.mdx` for the full design.
+ */
+export interface ParallelIterationContext {
+    mode: "parallel";
+    /** Index of the iteration whose inner step threw the wait. */
+    waitFiringIteration: number;
+    /** Inner step index within the wait-firing iteration's body. */
+    innerStepIndex: number;
+    /**
+     * Sparse array indexed by iteration number. Slot `i` is populated
+     * iff iteration `i` finished before the wait fired. `null` means
+     * "ran but returned undefined" (distinct from the JSON-undefined
+     * hole = "not present in cursor, re-launch on resume").
+     */
+    completedResults: (unknown | null)[];
+    /**
+     * Iteration indices that were in-flight OR queued at wait-throw
+     * moment. ForEachNode re-launches these from inner step 0 on
+     * resume. The wait-firing iteration is NOT in this list — it
+     * resumes via `innerStepIndex`. Sorted ascending for trace-dump
+     * readability.
+     */
+    cancelledIterations: number[];
 }
 /**
  * Stored result of a previously-successful step execution, keyed by
@@ -328,6 +511,26 @@ export interface ScheduledDispatchRow {
     payload: unknown;
     /** ms since epoch when the row was first written. */
     createdAt: number;
+    /**
+     * Tier C #2 — cross-process scheduler coordination. Set when a
+     * process claims this dispatch during boot recovery. Unset on
+     * unclaimed rows.
+     *
+     * Multi-process PG deployments use the claim to prevent the same
+     * dispatch from being fired by two processes that both ran
+     * `recoverDispatches()` against the shared table. Single-process
+     * and per-process sqlite deployments see no observable difference
+     * (the same process always wins the claim).
+     */
+    claimedBy?: string;
+    /**
+     * Tier C #2 — last heartbeat timestamp (ms since epoch). The
+     * holder of `claimedBy` periodically refreshes `claimedAt` while
+     * the timer is registered. Stale claims (now > claimedAt + leaseMs)
+     * are eligible for takeover by another process — protects against
+     * crashed holders blocking recovery indefinitely.
+     */
+    claimedAt?: number;
 }
 export type RunEventType = "RUN_STARTED" | "RUN_COMPLETED" | "RUN_FAILED" | "NODE_STARTED" | "NODE_COMPLETED" | "NODE_FAILED" | "NODE_SKIPPED" | "VARS_UPDATED" | "LOG_ENTRY"
 /** §17 Phase 5: streaming `Progress` frame from the SDK. */
@@ -443,6 +646,26 @@ export interface WorkflowDetail extends WorkflowSummary {
     definition?: unknown;
     nodeNames: string[];
     runtimes: string[];
+    /**
+     * Sample-body for the Studio empty-state curl. `source` lets the
+     * UI optionally distinguish author-declared examples from the
+     * synthesized ones (it doesn't today, but could in the future).
+     * Always populated for object-shaped workflows; `body` is `{}`
+     * when no body references were detected.
+     */
+    examples?: {
+        body: unknown;
+        /**
+         * Provenance of the body. `author` = declared in the workflow's
+         * `trigger.http.examples.body`. `recorded` = captured from the
+         * first successful run when `recordSample: true` is set on the
+         * trigger. `inferred` = synthesized from static analysis of step
+         * inputs. `empty` = no body references + no recording + no
+         * author override (the literal `{}`). Studio surfaces this in
+         * the Runs-tab empty-state curl snippet label.
+         */
+        source: "author" | "recorded" | "inferred" | "empty";
+    };
 }
 export interface PaginatedResult<T> {
     data: T[];
@@ -509,6 +732,13 @@ export interface StartNodeOptions {
      * Persisted onto `NodeRun.wait` so Studio can render `↳ async` vs `↳ sub`.
      */
     wait?: boolean;
+    /**
+     * G2 (v0.6) sub-workflow dispatch strategy. Only meaningful when
+     * `nodeType === "subworkflow"`. Persisted onto `NodeRun.dispatch` so
+     * Studio can render an extra `http` badge alongside `↳ async`/`↳ sub`
+     * for HTTP self-call dispatches.
+     */
+    dispatch?: "in-process" | "http-self";
     /**
      * PR 5 E3 — sub-workflow nesting depth. Only meaningful when
      * `nodeType === "subworkflow"`. The runner computes
@@ -516,6 +746,23 @@ export interface StartNodeOptions {
      * passes here so Studio can render `↳ sub (N)` for N >= 2.
      */
     subworkflowDepth?: number;
+    /**
+     * v0.5 — origin middleware name. Set when the parent ctx carries
+     * `_blokMiddlewareName` (HttpTrigger.runMiddlewareChain stash).
+     * Propagates onto `NodeRun.middleware` so Studio's StepRail can
+     * surface a `mw:<name>` badge.
+     */
+    middleware?: string;
+    /**
+     * v0.5.3 — iteration index for steps inside a `forEach` or `loop`
+     * primitive. Set when the parent ctx carries `_blokIterationIndex`
+     * (ForEachNode + LoopNode stash on each per-iteration child ctx).
+     * Studio's StepRail uses this to group consecutive sibling rows
+     * into "iteration N" sections instead of showing them flat with
+     * duplicated step names. Undefined for top-level steps and for
+     * inner steps of non-iteration primitives (`tryCatch`, `switch`).
+     */
+    iterationIndex?: number;
 }
 export type WidgetType = "stat-card" | "timeline" | "error-rate" | "duration-distribution" | "workflow-breakdown" | "node-performance" | "recent-runs" | "heatmap";
 export interface DashboardWidget {
@@ -545,19 +792,96 @@ export interface Dashboard {
     updatedAt: number;
     widgets: DashboardWidget[];
 }
+/**
+ * E2 — server-side saved filter for the runs list. Mirrors the
+ * earlier localStorage shape (`apps/studio/src/lib/savedFilters.ts`)
+ * with `id` + timestamps added. Filter names are UNIQUE across the
+ * deployment — re-saving overwrites the existing row. Studio applies
+ * them by setting the run-list filter UI from the stored values.
+ */
+export interface SavedFilter {
+    id: string;
+    name: string;
+    /** Workflow run status (`""` for "all"). */
+    status: string;
+    /**
+     * Free-form tag input as the user typed it ("env:prod,team:billing").
+     * Server stores it verbatim; the run-list URL parser interprets it.
+     */
+    tagsInput: string;
+    /**
+     * Free-form metadata input as the user typed it
+     * ("tier=premium,region__in=us,eu"). Same parsing contract as the
+     * runs-page URL — `MetadataFilter[]` once parsed.
+     */
+    metadataInput: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Sample-body recording (v0.6 follow-up to #100). When a workflow's
+ * HTTP trigger declares `recordSample: true`, the trigger captures
+ * the request body of the FIRST successful run and persists it
+ * here. Studio's `examples.body` resolution prefers a recorded
+ * sample over static inference but always defers to an author-
+ * declared `trigger.http.examples.body`.
+ *
+ * One row per workflow — re-recording is intentionally skipped
+ * after the first capture so storage stays bounded + the
+ * operator-visible example stays stable. Authors can re-trigger a
+ * recording by deleting the row (no Studio surface for this yet;
+ * call `tracker.deleteWorkflowSample(name)` from a script).
+ */
+export interface WorkflowSample {
+    workflowName: string;
+    body: unknown;
+    /** Run id whose request body was captured. */
+    sourceRunId: string;
+    /** Wall-clock when the sample was recorded. */
+    recordedAt: number;
+}
+/**
+ * F2 (v0.5) — operators accepted on metadata filters. `eq` is the
+ * default (and the only one available before v0.5). Each operator
+ * coerces values the way an operator typically would: numerical
+ * comparisons cast to number, `like` is SQL `LIKE` (with `%` /
+ * `_` wildcards), `in`/`nin` accept array values.
+ */
+export type MetadataOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "like" | "in" | "nin";
+/**
+ * F2 (v0.5) — operator-aware metadata filter. Combines with other
+ * filters in the same `RunQuery.metadata` array via AND semantics.
+ *
+ * `value` is `string` for scalar operators (`eq` / `ne` / `gt` / `lt` /
+ * `gte` / `lte` / `like`), `string[]` for set operators (`in` / `nin`).
+ * Numeric comparisons treat the stored metadata value as a number when
+ * possible (the underlying JSON store preserves the native type).
+ */
+export interface MetadataFilter {
+    key: string;
+    op: MetadataOp;
+    value: string | string[];
+}
 export interface RunQuery {
     workflow?: string;
     status?: WorkflowRunStatus;
     tags?: string[];
     /**
-     * Tier 2 quick-wins — filter by metadata key=value pairs. Multiple
-     * pairs combine with AND semantics (a run matches only when all
-     * declared keys match the requested values, compared via stringified
-     * equality). Backed by `json_extract` on SQLite + `Object` lookup
-     * on InMemory. Sequential scan (no index); acceptable given the
-     * `evictOldRuns` size cap on the runs table.
+     * Filter by metadata key/value pairs. Multiple entries combine with
+     * AND semantics (a run matches only when every declared filter is
+     * satisfied).
+     *
+     * **Two accepted shapes** — `Record<string, string>` is back-compat
+     * sugar for an array of `{key, op: "eq", value}` filters. Pass an
+     * array to use operators beyond `=` (F2: `ne` / `gt` / `gte` / `lt`
+     * / `lte` / `like` / `in` / `nin`). Both shapes route through the
+     * same evaluator after normalisation.
+     *
+     * **Performance** — sequential JSON-extract scan by default;
+     * declare hot keys via `BLOK_INDEXED_METADATA_KEYS=tier,region` to
+     * get an indexed column + index on the SqliteRunStore side (F1).
      */
-    metadata?: Record<string, string>;
+    metadata?: Record<string, string> | MetadataFilter[];
     limit?: number;
     offset?: number;
     sort?: "asc" | "desc";

package/dist/utils/envAllowlist.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Operator-controlled allowlist for `ctx.env` exposed to user nodes.
+ *
+ * By default `ctx.env` mirrors `process.env` — every node sees every
+ * env var. Operators harden against accidental secret leakage by
+ * setting one or both of:
+ *
+ * - `BLOK_NODE_ENV_ALLOW` — comma-separated exact names. Example:
+ *   `BLOK_NODE_ENV_ALLOW=DATABASE_URL,STRIPE_KEY`
+ * - `BLOK_NODE_ENV_ALLOW_PREFIX` — comma-separated prefixes. Example:
+ *   `BLOK_NODE_ENV_ALLOW_PREFIX=PUBLIC_,SAFE_`
+ *
+ * When EITHER is set, `ctx.env` becomes a Proxy that returns
+ * `undefined` for keys not in the allowlist and excludes them from
+ * `Object.keys`/`for...in`/`hasOwnProperty`. When NEITHER is set,
+ * `ctx.env` is `process.env` directly (preserves v0.4.x semantics —
+ * no breaking change).
+ *
+ * Set `BLOK_SUPPRESS_ENV_ALLOW_WARNING=1` to silence the boot warning
+ * that fires when `BLOK_ENV=production` and no allowlist is configured.
+ *
+ * The allowlist is parsed on every `getEnvForCtx()` call (creating a
+ * Context). Cost is sub-microsecond — strings are small and the
+ * Proxy is allocated once per request. Tests can mutate
+ * `process.env.BLOK_NODE_ENV_ALLOW` between calls and see the change
+ * immediately (no module-load caching).
+ */
+/**
+ * Returns the object to assign to `ctx.env`. When no allowlist is
+ * configured, returns `process.env` (default-allow). When configured,
+ * returns a filtering Proxy. Called by `TriggerBase.createContext`.
+ */
+export declare function getEnvForCtx(): NodeJS.ProcessEnv;
+/** Test-only — clears the once-per-process production warning flag. */
+export declare function _resetEnvAllowlistForTests(): void;

package/dist/utils/envAllowlist.js

@@ -0,0 +1,113 @@
+/**
+ * Operator-controlled allowlist for `ctx.env` exposed to user nodes.
+ *
+ * By default `ctx.env` mirrors `process.env` — every node sees every
+ * env var. Operators harden against accidental secret leakage by
+ * setting one or both of:
+ *
+ * - `BLOK_NODE_ENV_ALLOW` — comma-separated exact names. Example:
+ *   `BLOK_NODE_ENV_ALLOW=DATABASE_URL,STRIPE_KEY`
+ * - `BLOK_NODE_ENV_ALLOW_PREFIX` — comma-separated prefixes. Example:
+ *   `BLOK_NODE_ENV_ALLOW_PREFIX=PUBLIC_,SAFE_`
+ *
+ * When EITHER is set, `ctx.env` becomes a Proxy that returns
+ * `undefined` for keys not in the allowlist and excludes them from
+ * `Object.keys`/`for...in`/`hasOwnProperty`. When NEITHER is set,
+ * `ctx.env` is `process.env` directly (preserves v0.4.x semantics —
+ * no breaking change).
+ *
+ * Set `BLOK_SUPPRESS_ENV_ALLOW_WARNING=1` to silence the boot warning
+ * that fires when `BLOK_ENV=production` and no allowlist is configured.
+ *
+ * The allowlist is parsed on every `getEnvForCtx()` call (creating a
+ * Context). Cost is sub-microsecond — strings are small and the
+ * Proxy is allocated once per request. Tests can mutate
+ * `process.env.BLOK_NODE_ENV_ALLOW` between calls and see the change
+ * immediately (no module-load caching).
+ */
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function loadConfig() {
+    const allow = parseList(process.env.BLOK_NODE_ENV_ALLOW);
+    const prefixes = parseList(process.env.BLOK_NODE_ENV_ALLOW_PREFIX);
+    if (allow.length === 0 && prefixes.length === 0)
+        return null;
+    return { allow, prefixes };
+}
+function isAllowed(key, config) {
+    if (config.allow.includes(key))
+        return true;
+    for (const p of config.prefixes) {
+        if (key.startsWith(p))
+            return true;
+    }
+    return false;
+}
+/**
+ * Build a Proxy around `process.env` that hides keys not in the
+ * allowlist. Reads of denied keys return `undefined`; iteration via
+ * `Object.keys` / `for...in` / `Object.entries` excludes them; `key
+ * in env` returns `false`. Writes pass through (operators don't lose
+ * the ability for nodes to mutate process.env if they want to — the
+ * filter is a read gate, not a sandbox).
+ */
+function buildProxy(config) {
+    return new Proxy(process.env, {
+        get(target, key) {
+            if (typeof key !== "string")
+                return undefined;
+            return isAllowed(key, config) ? target[key] : undefined;
+        },
+        has(target, key) {
+            if (typeof key !== "string")
+                return false;
+            return isAllowed(key, config) && key in target;
+        },
+        ownKeys(target) {
+            return Object.keys(target).filter((k) => isAllowed(k, config));
+        },
+        getOwnPropertyDescriptor(target, key) {
+            if (typeof key !== "string" || !isAllowed(key, config))
+                return undefined;
+            return Object.getOwnPropertyDescriptor(target, key);
+        },
+    });
+}
+let productionWarningEmitted = false;
+function emitProductionWarning() {
+    if (productionWarningEmitted)
+        return;
+    productionWarningEmitted = true;
+    if (process.env.BLOK_SUPPRESS_ENV_ALLOW_WARNING === "1")
+        return;
+    if (process.env.BLOK_ENV !== "production")
+        return;
+    console.warn("[blok] BLOK_ENV=production but neither BLOK_NODE_ENV_ALLOW nor BLOK_NODE_ENV_ALLOW_PREFIX is set. " +
+        "Every loaded node sees every env var, including secrets. " +
+        "Configure an allowlist to harden the surface, or set " +
+        "BLOK_SUPPRESS_ENV_ALLOW_WARNING=1 to silence.");
+}
+/**
+ * Returns the object to assign to `ctx.env`. When no allowlist is
+ * configured, returns `process.env` (default-allow). When configured,
+ * returns a filtering Proxy. Called by `TriggerBase.createContext`.
+ */
+export function getEnvForCtx() {
+    const config = loadConfig();
+    if (!config) {
+        emitProductionWarning();
+        return process.env;
+    }
+    return buildProxy(config);
+}
+/** Test-only — clears the once-per-process production warning flag. */
+export function _resetEnvAllowlistForTests() {
+    productionWarningEmitted = false;
+}
+//# sourceMappingURL=envAllowlist.js.map

package/dist/utils/envAllowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envAllowlist.js","sourceRoot":"","sources":["../../src/utils/envAllowlist.ts"],"names":[],"mappings":"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"}

package/dist/version/RuntimeVersionValidator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RuntimeVersionValidator — Validates node and workflow runtime version requirements.
+ *
+ * Used by the runner to check that nodes' `runtimeRequirements` are satisfied
+ * by the currently running runtime versions before executing workflows.
+ */
+export interface VersionValidationResult {
+    valid: boolean;
+    node: string;
+    runtime: string;
+    required: string;
+    actual: string | undefined;
+    message: string;
+}
+export declare class RuntimeVersionValidator {
+    private runtimeVersions;
+    constructor(runtimeVersions?: Record<string, string>);
+    setRuntimeVersion(kind: string, version: string): void;
+    getRuntimeVersion(kind: string): string | undefined;
+    /**
+     * Validate a single node's runtime requirements against known runtime versions.
+     */
+    validateNode(node: {
+        name: string;
+        runtimeRequirements?: Partial<Record<string, string>>;
+    }): VersionValidationResult[];
+    /**
+     * Validate all nodes in a workflow against known runtime versions.
+     */
+    validateWorkflow(nodes: Array<{
+        name: string;
+        runtimeRequirements?: Partial<Record<string, string>>;
+    }>): VersionValidationResult[];
+    /**
+     * Format validation errors into a user-friendly multi-line string.
+     */
+    static formatErrors(results: VersionValidationResult[]): string;
+}