@xdelivered/emberflow 0.2.0

package/dist/server/runtime/expressAdapter.js

@@ -0,0 +1,56 @@
+import express, {} from 'express';
+const METHODS = ['get', 'post', 'put', 'delete', 'patch'];
+function isMethod(m) {
+    return METHODS.includes(m);
+}
+/** Express implementation of the `RuntimeAdapter` seam. Keep it thin — this is
+ *  the seam other runtimes (Deno/Bun) implement later. */
+export class ExpressAdapter {
+    _app;
+    server;
+    seen = new Set();
+    constructor(app) {
+        this._app = app ?? express();
+    }
+    get app() {
+        return this._app;
+    }
+    /** The bound address once `listen()` resolves (useful in tests to find an
+     *  ephemeral port). `null` before listening / after close. */
+    get address() {
+        const addr = this.server?.address();
+        return addr && typeof addr === 'object' ? addr : null;
+    }
+    registerOperation(op, handler) {
+        const method = op.method.toUpperCase();
+        const key = `${method} ${op.path}`;
+        if (this.seen.has(key)) {
+            throw new Error(`Duplicate operation route: ${key}`);
+        }
+        const lower = method.toLowerCase();
+        if (!isMethod(lower)) {
+            throw new Error(`Unsupported HTTP method for operation route: ${method} ${op.path}`);
+        }
+        this.seen.add(key);
+        this._app[lower](op.path, handler);
+    }
+    mountRouter(basePath, router) {
+        this._app.use(basePath, router);
+    }
+    listen(port, host) {
+        return new Promise((resolve) => {
+            this.server = this._app.listen(port, host, () => resolve());
+        });
+    }
+    close() {
+        return new Promise((resolve, reject) => {
+            const server = this.server;
+            if (!server) {
+                resolve();
+                return;
+            }
+            this.server = undefined;
+            server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+}

package/dist/server/scenarioTest.d.ts

@@ -0,0 +1,14 @@
+import type { ScenarioExpectation, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
+/** Deep-subset match: every key/index present in `expected` must match the
+ *  corresponding key/index in `actual`, recursively. Extra keys/indices in
+ *  `actual` are ignored. `null` matches only `null`. Returns human-readable
+ *  failure strings with dotted (and `[i]`) paths; empty array = match. */
+export declare function deepSubsetMatch(expected: unknown, actual: unknown, path?: string): string[];
+/** Check a scenario's finished run against its `expect` assertion. `status`/
+ *  `body` come from `extractResponse` (the flow's Response-node mapping,
+ *  defaulting to status 200); `executedNodes` checks each id's node state is
+ *  `succeeded`. */
+export declare function evaluateExpectation(run: WorkflowRun, flow: WorkflowDefinition, expect: ScenarioExpectation): {
+    ok: boolean;
+    failures: string[];
+};

package/dist/server/scenarioTest.js

@@ -0,0 +1,66 @@
+import { extractResponse } from './operationResult.js';
+function fmt(value) {
+    if (value === undefined)
+        return 'undefined';
+    return JSON.stringify(value);
+}
+/** Deep-subset match: every key/index present in `expected` must match the
+ *  corresponding key/index in `actual`, recursively. Extra keys/indices in
+ *  `actual` are ignored. `null` matches only `null`. Returns human-readable
+ *  failure strings with dotted (and `[i]`) paths; empty array = match. */
+export function deepSubsetMatch(expected, actual, path = '') {
+    const label = path === '' ? '' : `${path}: `;
+    if (expected === null) {
+        return actual === null ? [] : [`${label}expected null, got ${fmt(actual)}`];
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual)) {
+            return [`${label}expected array, got ${fmt(actual)}`];
+        }
+        const failures = [];
+        for (let i = 0; i < expected.length; i++) {
+            failures.push(...deepSubsetMatch(expected[i], actual[i], `${path}[${i}]`));
+        }
+        return failures;
+    }
+    if (typeof expected === 'object') {
+        if (typeof actual !== 'object' || actual === null || Array.isArray(actual)) {
+            return [`${label}expected object, got ${fmt(actual)}`];
+        }
+        const failures = [];
+        for (const key of Object.keys(expected)) {
+            const childPath = path === '' ? key : `${path}.${key}`;
+            failures.push(...deepSubsetMatch(expected[key], actual[key], childPath));
+        }
+        return failures;
+    }
+    // Primitive.
+    return expected === actual ? [] : [`${label}expected ${fmt(expected)}, got ${fmt(actual)}`];
+}
+/** Check a scenario's finished run against its `expect` assertion. `status`/
+ *  `body` come from `extractResponse` (the flow's Response-node mapping,
+ *  defaulting to status 200); `executedNodes` checks each id's node state is
+ *  `succeeded`. */
+export function evaluateExpectation(run, flow, expect) {
+    const failures = [];
+    if (expect.status !== undefined || expect.body !== undefined) {
+        const { status, body } = extractResponse(run, flow);
+        if (expect.status !== undefined && expect.status !== status) {
+            failures.push(`status: expected ${expect.status}, got ${status}`);
+        }
+        if (expect.body !== undefined) {
+            for (const failure of deepSubsetMatch(expect.body, body)) {
+                failures.push(`body.${failure}`);
+            }
+        }
+    }
+    if (expect.executedNodes) {
+        for (const id of expect.executedNodes) {
+            const state = run.nodeStates[id];
+            if (state?.status !== 'succeeded') {
+                failures.push(`executedNodes: ${id} did not execute (status: ${state?.status ?? 'not run'})`);
+            }
+        }
+    }
+    return { ok: failures.length === 0, failures };
+}

package/dist/server/subflowRunner.d.ts

@@ -0,0 +1,32 @@
+import type { LogLine, NodeRegistry, StartRunOptions, TraceSink, WorkflowDefinition } from '../src/engine/index.js';
+/** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
+export declare const SUBFLOW_DEPTH_CAP = 8;
+export interface SubflowRunnerOptions {
+    /** Resolves a child workflow by id (server hosts this via apiStore.load). */
+    loadFlow: (id: string) => WorkflowDefinition | undefined;
+    registry: NodeRegistry;
+    secrets: Record<string, string>;
+    vars: Record<string, string>;
+    environment: string;
+    safeMode: boolean;
+    /** When true, child runs execute in Mock mode too — nothing real is ever
+     *  touched during a mock run, including inside Subflow children. See
+     *  `StartRunOptions.mockRun`. */
+    mockRun?: boolean;
+    /** Optional trace sink shared with the parent run (SSE/samples plumbing). */
+    trace?: TraceSink;
+    /** Optional child-log forwarder — receives the child's log lines already
+     *  prefixed with the child flow's name and the caller node's id, exactly as
+     *  the live runner streams them over SSE. Absent for headless runs. */
+    onLog?: (line: LogLine) => void;
+}
+/**
+ * Shared Subflow-runner factory used by BOTH the live runner
+ * (server/runRegistry.ts) and the in-process test runner
+ * (server/testRunner.ts): resolve the child via `loadFlow`, run it to
+ * completion on the same registry sharing the parent's environment
+ * (secrets/vars/safeMode), and return its collected Result output. The
+ * ancestry chain enforces the depth cap and catches A→B→A cycles; nested
+ * children keep their own execution sequence.
+ */
+export declare function makeSubflowRunner(opts: SubflowRunnerOptions, ancestry: string[]): NonNullable<StartRunOptions['subflowRunner']>;

package/dist/server/subflowRunner.js

@@ -0,0 +1,72 @@
+import { runOutput, startRun } from '../src/engine/index.js';
+/** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
+export const SUBFLOW_DEPTH_CAP = 8;
+/**
+ * Shared Subflow-runner factory used by BOTH the live runner
+ * (server/runRegistry.ts) and the in-process test runner
+ * (server/testRunner.ts): resolve the child via `loadFlow`, run it to
+ * completion on the same registry sharing the parent's environment
+ * (secrets/vars/safeMode), and return its collected Result output. The
+ * ancestry chain enforces the depth cap and catches A→B→A cycles; nested
+ * children keep their own execution sequence.
+ */
+export function makeSubflowRunner(opts, ancestry) {
+    return async (workflowId, input, callerNodeId) => {
+        if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
+            return { status: 'failed', error: `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded` };
+        }
+        if (ancestry.includes(workflowId)) {
+            return { status: 'failed', error: `subflow cycle: ${[...ancestry, workflowId].join(' → ')}` };
+        }
+        const childFlow = opts.loadFlow(workflowId);
+        if (!childFlow)
+            return { status: 'failed', error: `Unknown workflow: ${workflowId}` };
+        try {
+            const childHandle = startRun({
+                flow: childFlow,
+                registry: opts.registry,
+                secrets: opts.secrets,
+                vars: opts.vars,
+                environment: opts.environment,
+                safeMode: opts.safeMode,
+                input,
+                // Mock mode propagates into the child: nothing real is ever touched
+                // in a mock run, including inside Subflow children. Scenario context
+                // never propagates (the parent didn't pick one for the child) — only
+                // the CHILD op's own op-level mocks apply, since nodeIds are scoped
+                // per-flow and reusing the parent's mock map would be meaningless
+                // (or worse, silently wrong) for the child's node ids.
+                mockRun: opts.mockRun,
+                mocks: childFlow.mocks ?? {},
+                trace: opts.trace,
+                subflowRunner: makeSubflowRunner(opts, [...ancestry, workflowId]),
+                events: opts.onLog
+                    ? {
+                        onLog: (line) => opts.onLog({
+                            ...line,
+                            nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
+                            nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
+                        }),
+                    }
+                    : undefined,
+            });
+            const childRun = await childHandle.runToEnd();
+            if (childRun.status !== 'succeeded') {
+                // Surface the child's actual failure (e.g. the Mock-mode "would touch
+                // real infrastructure" boundary message) through the Subflow node's
+                // own error, rather than an opaque "failed" — the first failed
+                // node's `error`, if any, wins.
+                const failedNode = Object.values(childRun.nodeStates).find((s) => s.status === 'failed' && s.error);
+                const detail = failedNode?.error;
+                return {
+                    status: 'failed',
+                    error: `subflow "${childFlow.name}" ${childRun.status}${detail ? `: ${detail}` : ''}`,
+                };
+            }
+            return { status: 'succeeded', output: runOutput(childRun, childFlow) };
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+    };
+}

package/dist/server/testRunner.d.ts

@@ -0,0 +1,70 @@
+import { type NodeRegistry } from '../src/engine/index.js';
+import { type EnvironmentsFile } from './environments.js';
+import type { ApiStore } from './apiStore.js';
+/** Thrown for CLI usage errors (unknown opId / unknown environment) — the CLI
+ *  layer turns this into exit code 2, distinct from an assertion failure
+ *  (exit 1) or an unexpected error (also exit 1, via runCli's generic catch). */
+export declare class ScenarioTestUsageError extends Error {
+}
+export type SkipReason = 'no expect' | 'empty expect';
+export interface ScenarioResult {
+    opId: string;
+    scenario: string;
+    status: 'passed' | 'failed' | 'skipped';
+    /** Present only when status === 'failed' — evaluateExpectation's failure strings. */
+    failures?: string[];
+    /** Present only when status === 'skipped'. */
+    reason?: SkipReason;
+}
+export interface TestReport {
+    results: ScenarioResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+}
+/**
+ * Runs every scenario with `expect` across the given ops (or a single op when
+ * `opId` is given), entirely in-process: `startRun` is called directly per
+ * scenario, mirroring the options shape `RunRegistry.create` passes
+ * (server/runRegistry.ts) — but bypassing RunRegistry entirely, so these runs
+ * never enter it (no SSE, no run history).
+ *
+ * This is the shared seam both the CLI (`runScenarioSuite`, which bootstraps
+ * its own project/registries/apiStore from disk) and the studio route
+ * (`POST /workflows/:id/test` in server/index.ts, which reuses the
+ * already-booted server's apiStore/registry/environmentsFile — no re-read
+ * from disk, no drift from in-memory writes) call into. NO second expectation
+ * engine — both paths land here.
+ *
+ * Throws `ScenarioTestUsageError` for usage problems (unknown opId, unknown
+ * environment) — the CLI layer maps that to exit code 2; the route maps it to
+ * 400/404.
+ */
+export declare function runScenarioSuiteFor(ctx: {
+    apiStore: ApiStore;
+    registry: NodeRegistry;
+    environmentsFile: EnvironmentsFile;
+}, opts: {
+    opId?: string;
+    environmentName?: string;
+    mock?: boolean;
+}): Promise<TestReport>;
+/**
+ * CLI entry point: bootstraps a project from disk (loadProjectConfig/
+ * buildRegistries/buildApiStore/loadEnvironments — the same bootstrap
+ * `server/index.ts` uses) and delegates to `runScenarioSuiteFor`. NO runner
+ * process, no HTTP.
+ */
+export declare function runScenarioSuite(opts: {
+    projectDir: string;
+    opId?: string;
+    environmentName?: string;
+    mock?: boolean;
+}): Promise<TestReport>;
+/** `✓ opId · scenario` / `✗ opId · scenario (failure; failure)` — undefined for
+ *  skipped scenarios, which aren't printed as individual lines (only counted
+ *  in the summary), keeping default output focused on assertable scenarios. */
+export declare function formatScenarioLine(r: ScenarioResult): string | undefined;
+/** `12 passed, 1 failed, 3 skipped (no expect)` — the parenthetical lists the
+ *  distinct skip reasons present (omitted entirely when nothing was skipped). */
+export declare function formatSummary(report: TestReport): string;

package/dist/server/testRunner.js

@@ -0,0 +1,151 @@
+import { mergeMocks, startRun, } from '../src/engine/index.js';
+import { loadProjectConfig } from './projectConfig.js';
+import { buildApiStore, buildRegistries, requireProjectWhenExplicit } from './projectMode.js';
+import { loadEnvironments, resolveRunSafety } from './environments.js';
+import { evaluateExpectation } from './scenarioTest.js';
+import { makeSubflowRunner } from './subflowRunner.js';
+import { redactSecrets } from './redact.js';
+/** Thrown for CLI usage errors (unknown opId / unknown environment) — the CLI
+ *  layer turns this into exit code 2, distinct from an assertion failure
+ *  (exit 1) or an unexpected error (also exit 1, via runCli's generic catch). */
+export class ScenarioTestUsageError extends Error {
+}
+async function runScenario(op, scenario, apiStore, registry, env, mock) {
+    if (!scenario.expect) {
+        return { opId: op.id, scenario: scenario.name, status: 'skipped', reason: 'no expect' };
+    }
+    if (Object.keys(scenario.expect).length === 0) {
+        return { opId: op.id, scenario: scenario.name, status: 'skipped', reason: 'empty expect' };
+    }
+    // INTENTIONAL (controller decision): NO environment auth auto-attach here,
+    // unlike POST /runs (server/index.ts attachCredential). Tests are hermetic —
+    // auto-attaching the environment's credential would silently satisfy the very
+    // auth checks a deliberate 401-expectation scenario exists to exercise. If a
+    // scenario needs auth, embed the headers directly in `scenario.input`.
+    //
+    // --mock: same merge as the live serving mock-run path (mergeMocks,
+    // src/engine/scenarios.ts) — op-level `flow.mocks` overlaid by this
+    // scenario's `mocks`, scenario wins per nodeId. Nothing real is ever
+    // touched: the executor's mockRun short-circuit fails loudly on any
+    // infrastructure node (traceKind db/http/llm) that has no mock.
+    const handle = startRun({
+        flow: op,
+        registry,
+        secrets: env.secrets,
+        vars: env.vars,
+        environment: env.environment,
+        safeMode: env.safeMode,
+        input: scenario.input,
+        mockRun: mock,
+        mocks: mock ? mergeMocks(op, scenario) : undefined,
+        // Shared factory (server/subflowRunner.ts) — same depth cap/cycle guard as
+        // the live runner, minus the SSE trace/log plumbing a headless run skips.
+        subflowRunner: makeSubflowRunner({
+            loadFlow: (id) => apiStore.load(id),
+            registry,
+            secrets: env.secrets,
+            vars: env.vars,
+            environment: env.environment,
+            safeMode: env.safeMode,
+            mockRun: mock,
+        }, [op.id]),
+    });
+    const run = await handle.runToEnd();
+    const { ok, failures } = evaluateExpectation(run, op, scenario.expect);
+    return {
+        opId: op.id,
+        scenario: scenario.name,
+        status: ok ? 'passed' : 'failed',
+        ...(ok ? {} : { failures }),
+    };
+}
+/**
+ * Runs every scenario with `expect` across the given ops (or a single op when
+ * `opId` is given), entirely in-process: `startRun` is called directly per
+ * scenario, mirroring the options shape `RunRegistry.create` passes
+ * (server/runRegistry.ts) — but bypassing RunRegistry entirely, so these runs
+ * never enter it (no SSE, no run history).
+ *
+ * This is the shared seam both the CLI (`runScenarioSuite`, which bootstraps
+ * its own project/registries/apiStore from disk) and the studio route
+ * (`POST /workflows/:id/test` in server/index.ts, which reuses the
+ * already-booted server's apiStore/registry/environmentsFile — no re-read
+ * from disk, no drift from in-memory writes) call into. NO second expectation
+ * engine — both paths land here.
+ *
+ * Throws `ScenarioTestUsageError` for usage problems (unknown opId, unknown
+ * environment) — the CLI layer maps that to exit code 2; the route maps it to
+ * 400/404.
+ */
+export async function runScenarioSuiteFor(ctx, opts) {
+    const { apiStore, registry, environmentsFile } = ctx;
+    const { opId, environmentName, mock = false } = opts;
+    const envName = environmentName ?? environmentsFile.defaultEnvironment;
+    const envDef = environmentsFile.environments[envName];
+    if (!envDef) {
+        throw new ScenarioTestUsageError(`Unknown environment: '${envName}'`);
+    }
+    const safety = resolveRunSafety(envName, envDef, {});
+    const runEnv = {
+        secrets: envDef.secrets,
+        vars: envDef.vars,
+        environment: envName,
+        safeMode: safety.ok ? safety.safeMode : false,
+    };
+    const allOps = apiStore.list();
+    let targetOps = allOps;
+    if (opId !== undefined) {
+        const op = allOps.find((o) => o.id === opId);
+        if (!op)
+            throw new ScenarioTestUsageError(`Unknown operation: '${opId}'`);
+        targetOps = [op];
+    }
+    const rawResults = [];
+    for (const op of targetOps) {
+        for (const scenario of op.scenarios ?? []) {
+            rawResults.push(await runScenario(op, scenario, apiStore, registry, runEnv, mock));
+        }
+    }
+    // evaluateExpectation diffs RAW run state, so a failure string can quote a
+    // secret value the flow echoed into its response body. Redact the whole
+    // reporter payload (value-based; raw/url-encoded/base64 forms) before it can
+    // reach stdout/CI logs — same redactSecrets the SSE event path uses.
+    const results = redactSecrets(rawResults, runEnv.secrets);
+    return {
+        results,
+        passed: results.filter((r) => r.status === 'passed').length,
+        failed: results.filter((r) => r.status === 'failed').length,
+        skipped: results.filter((r) => r.status === 'skipped').length,
+    };
+}
+/**
+ * CLI entry point: bootstraps a project from disk (loadProjectConfig/
+ * buildRegistries/buildApiStore/loadEnvironments — the same bootstrap
+ * `server/index.ts` uses) and delegates to `runScenarioSuiteFor`. NO runner
+ * process, no HTTP.
+ */
+export async function runScenarioSuite(opts) {
+    const { projectDir, opId, environmentName, mock } = opts;
+    const project = requireProjectWhenExplicit(await loadProjectConfig(projectDir), process.env.EMBERFLOW_PROJECT, projectDir);
+    const environmentsFile = loadEnvironments(project ? project.root : projectDir);
+    const { execution } = buildRegistries(project);
+    const apiStore = buildApiStore(project);
+    return runScenarioSuiteFor({ apiStore, registry: execution, environmentsFile }, { opId, environmentName, mock });
+}
+/** `✓ opId · scenario` / `✗ opId · scenario (failure; failure)` — undefined for
+ *  skipped scenarios, which aren't printed as individual lines (only counted
+ *  in the summary), keeping default output focused on assertable scenarios. */
+export function formatScenarioLine(r) {
+    if (r.status === 'skipped')
+        return undefined;
+    if (r.status === 'passed')
+        return `✓ ${r.opId} · ${r.scenario}`;
+    return `✗ ${r.opId} · ${r.scenario} (${(r.failures ?? []).join('; ')})`;
+}
+/** `12 passed, 1 failed, 3 skipped (no expect)` — the parenthetical lists the
+ *  distinct skip reasons present (omitted entirely when nothing was skipped). */
+export function formatSummary(report) {
+    const reasons = [...new Set(report.results.filter((r) => r.status === 'skipped').map((r) => r.reason))];
+    const suffix = report.skipped > 0 ? ` (${reasons.join(', ')})` : '';
+    return `${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped${suffix}`;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,3 @@
+export { defineConfig } from '../server/projectConfig.js';
+export type { EmberflowUserConfig } from '../server/projectConfig.js';
+export type { NodeRegistry, NodeDefinition, NodeExecutionContext } from './engine/index.js';

package/dist/src/config.js

@@ -0,0 +1,2 @@
+// src/config.ts — the `emberflow` package root: what a consumer's emberflow.config imports.
+export { defineConfig } from '../server/projectConfig.js';

package/dist/src/engine/authVerify.d.ts

@@ -0,0 +1,33 @@
+import type { AuthPolicy } from './types.js';
+export interface VerifyResult {
+    user: unknown;
+}
+/** Given the request + the resolved secret value, return a user or throw HttpError(401). */
+export type Verifier = (args: {
+    request: {
+        headers: Record<string, unknown>;
+    };
+    policy: AuthPolicy;
+    secret: string | undefined;
+}) => VerifyResult;
+export declare const bearerVerifier: Verifier;
+export declare const apiKeyVerifier: Verifier;
+export declare class VerifierRegistry {
+    private map;
+    register(name: string, v: Verifier): void;
+    get(name: string): Verifier | undefined;
+}
+export declare function createDefaultVerifierRegistry(): VerifierRegistry;
+/**
+ * Picks the verifier (policy.verify ? verifiers.get(policy.verify) : verifiers.get(policy.scheme)),
+ * fails closed with HttpError(500) if it's missing, resolves the secret from
+ * `secrets[policy.secretRef]`, and runs the verifier (its HttpError, if any, propagates).
+ */
+export declare function enforceAuth(args: {
+    policy: AuthPolicy;
+    request: {
+        headers: Record<string, unknown>;
+    };
+    secrets: Record<string, unknown>;
+    verifiers: VerifierRegistry;
+}): VerifyResult;

package/dist/src/engine/authVerify.js

@@ -0,0 +1,63 @@
+// Browser-safe auth verification core. Lives here (not under server/auth/)
+// because src/nodes/requireAuth.ts (bundled into the studio browser build via
+// src/store/builderStore.ts -> src/nodes) must not import from server/. The
+// server-side enforce.ts + verifiers.ts re-export/wrap this module so there's
+// a single implementation instead of two diverging copies.
+import { HttpError } from './httpError.js';
+const bearerToken = (headers) => {
+    const raw = headers['authorization'] ?? headers['Authorization'];
+    if (typeof raw !== 'string')
+        return undefined;
+    const m = /^Bearer\s+(.+)$/i.exec(raw);
+    return m ? m[1] : undefined;
+};
+// Note: a plain string comparison is used here rather than a timing-safe
+// comparison; timing-safe comparison is a later hardening item.
+export const bearerVerifier = ({ request, secret }) => {
+    if (secret === undefined)
+        throw new HttpError(500, { error: 'auth misconfigured: secret not set' });
+    const token = bearerToken(request.headers);
+    if (!token || token !== secret)
+        throw new HttpError(401, { error: 'unauthorized' });
+    return { user: { scheme: 'bearer' } };
+};
+export const apiKeyVerifier = ({ request, policy, secret }) => {
+    if (secret === undefined)
+        throw new HttpError(500, { error: 'auth misconfigured: secret not set' });
+    const headerName = (policy.header ?? 'x-api-key').toLowerCase();
+    const provided = request.headers[headerName];
+    if (typeof provided !== 'string' || provided !== secret)
+        throw new HttpError(401, { error: 'unauthorized' });
+    return { user: { scheme: 'apiKey' } };
+};
+export class VerifierRegistry {
+    map = new Map();
+    register(name, v) {
+        this.map.set(name, v);
+    }
+    get(name) {
+        return this.map.get(name);
+    }
+}
+export function createDefaultVerifierRegistry() {
+    const reg = new VerifierRegistry();
+    reg.register('bearer', bearerVerifier);
+    reg.register('apiKey', apiKeyVerifier);
+    return reg;
+}
+/**
+ * Picks the verifier (policy.verify ? verifiers.get(policy.verify) : verifiers.get(policy.scheme)),
+ * fails closed with HttpError(500) if it's missing, resolves the secret from
+ * `secrets[policy.secretRef]`, and runs the verifier (its HttpError, if any, propagates).
+ */
+export function enforceAuth(args) {
+    const { policy, request, secrets, verifiers } = args;
+    const verifierName = policy.verify ?? policy.scheme;
+    const verifier = policy.verify ? verifiers.get(policy.verify) : verifiers.get(policy.scheme);
+    if (!verifier) {
+        throw new HttpError(500, { error: `auth misconfigured: no verifier ${verifierName}` });
+    }
+    const rawSecret = secrets[policy.secretRef];
+    const secret = typeof rawSecret === 'string' ? rawSecret : undefined;
+    return verifier({ request, policy, secret });
+}

package/dist/src/engine/diagnostics.d.ts

@@ -0,0 +1,62 @@
+import type { ScenarioDefinition, WorkflowDefinition } from './types.js';
+export interface OperationDiagnostic {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    message: string;
+    nodeId?: string;
+    param?: string;
+}
+/** Registry-derived facts diagnoseOperation cannot compute on its own — it is
+ *  a pure function over (flow, scenarios) and has no node-definition lookup.
+ *  Callers that hold a registry (server/index.ts's diagnostics route, the
+ *  `doctor` CLI, the studio's client-side registry) derive `infraNodes` by
+ *  looking up each flow node's type and keeping the ones whose `traceKind` is
+ *  'db' | 'http' | 'llm'. Callers without a registry (or without meta yet)
+ *  omit `extras` entirely — `missing-node-mock` simply doesn't fire. */
+export interface DiagnoseOperationExtras {
+    infraNodes?: Array<{
+        id: string;
+        traceKind: string;
+    }>;
+    /** Op-level mocks to check coverage against, when the caller has a more
+     *  authoritative source than `flow.mocks` (e.g. an in-progress edit not yet
+     *  saved). Falls back to `flow.mocks` when omitted. */
+    opMocks?: Record<string, unknown>;
+    /** Declared output field names per flow-node id, for `inputmap-schema-mismatch`.
+     *  Callers that hold a registry populate this ONLY for nodes whose type is
+     *  registered AND whose outputSchema declares fields (an entry's presence is
+     *  the "checkable" signal). Nodes absent from the map — unregistered types, or
+     *  registered ones with an empty/absent outputSchema (Input, Subflow, …) — are
+     *  never flagged, so dynamic-output nodes cannot false-positive. Omitted
+     *  entirely → the diagnostic simply doesn't fire. */
+    outputFieldsByNode?: Record<string, string[]>;
+    /** Implementation source per flow-node id, for `simulated-commit`. Callers
+     *  that hold a registry populate this ONLY for nodes whose type is
+     *  registered AND whose registered `definition.effects === 'mutation'` AND
+     *  whose implementation is a function (`String(implementation)`). A node
+     *  absent from the map — unregistered type, non-mutation node, or a native/
+     *  bound implementation whose source isn't meaningfully inspectable — is
+     *  never flagged. Omitted entirely → the diagnostic simply doesn't fire. */
+    mutationSourcesByNode?: Record<string, string>;
+    /** Project-level signal for `language-drift`, NOT per-node. Pass this ONLY
+     *  when the project config's `language:` field was EXPLICIT and disagrees
+     *  with the config file's own extension (e.g. `language: 'javascript'` in
+     *  an `emberflow.config.ts`) — inference makes language and extension agree
+     *  by construction, so that's the only case worth flagging. Callers that
+     *  hold a loaded ProjectConfig (server/index.ts's diagnostics route, the
+     *  `doctor` CLI) plumb this from `ProjectConfig.languageDrift`. The studio
+     *  doesn't currently have project-language access client-side, so it omits
+     *  this and the diagnostic simply doesn't fire there. */
+    languageDrift?: {
+        projectLanguage: 'javascript' | 'typescript';
+        configPathExtension: string;
+    };
+}
+/** Diagnose an operation (a flow with an `http` trigger, plus its scenarios)
+ *  for issues a studio user or the `emberflow doctor` CLI should surface
+ *  before relying on the operation. Deterministic order: all
+ *  `missing-param-default` (path order), then all `param-no-real-scenario`
+ *  (path order), then `no-expects`, then `missing-node-mock` (extras order),
+ *  then `inputmap-schema-mismatch` (node order), then `simulated-commit`
+ *  (node order), then `language-drift` (at most one, project-level). */
+export declare function diagnoseOperation(flow: WorkflowDefinition, scenarios: ScenarioDefinition[] | undefined, extras?: DiagnoseOperationExtras): OperationDiagnostic[];