@flowmarkdev/node 0.0.0-stage → 0.1.0-alpha.1

package/dist/client/create-client.js

@@ -0,0 +1,136 @@
+import { FetchHttpClient } from "@effect/platform";
+import { Layer } from "effect";
+import { HttpTransportLive } from "../features/delivery/adapters/http.js";
+import { FlowmarkSettings, resolveSettings } from "../config/settings.js";
+import { FlowmarkConfigError } from "../errors/index.js";
+import { makeClient } from "./runtime.js";
+import { WorkflowTransport } from "../features/delivery/ports/workflow-transport.js";
+import { withOperationCallback } from "../utils/operation-callback.js";
+import { splitOperationArgs } from "../utils/operation-args.js";
+/**
+ * Node server client. Import this from `@flowmarkdev/node` in workers and scripts.
+ * Next.js Route Handlers must import createFlowmark from `@flowmarkdev/node/next`.
+ * Browser code must import it from `@flowmarkdev/node/browser`.
+ * Reads FLOWMARK_API_KEY and FLOWMARK_API_URL; never put those in NEXT_PUBLIC_*.
+ * Call shutdown() before process exit. Create one shared client.
+ * @throws FlowmarkConfigError If credentials or API origin are invalid.
+ */
+export function createFlowmark(config = {}) {
+    const settings = resolveSettings(config);
+    const transport = HttpTransportLive.pipe(Layer.provide(Layer.succeed(FlowmarkSettings, settings)), Layer.provide(FetchHttpClient.layer));
+    return makeClient(transport, config.onInstrumentationError, {
+        environment: config.environment,
+        release: config.release,
+    });
+}
+/**
+ * Advanced entry point for a custom Effect transport, primarily tests and custom integrations.
+ * Use createFlowmark().workflow() for ordinary application code.
+ * Delivery resources are drained and released after terminal completion. If
+ * operations are open, done() waits for their handles to close first.
+ * @param name Stable workflow name.
+ * @param options Explicit execution ID, transport, and optional diagnostics/metadata.
+ * @throws FlowmarkConfigError If no transport is supplied.
+ */
+export function workflow(name, options) {
+    if (!options.transport) {
+        throw new FlowmarkConfigError({
+            cause: "Use createFlowmark().workflow() for automatic delivery. The low-level workflow() entry point requires a custom transport.",
+        });
+    }
+    const client = makeClient(Layer.succeed(WorkflowTransport, options.transport), options.onInstrumentationError);
+    const flow = client.workflow(name, options);
+    let finished = false;
+    let completionRequested = false;
+    const activeOperations = new Set();
+    const finish = (command) => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        command();
+        void client.shutdown().catch(() => {
+            console.warn("[Flowmark] Custom transport workflow completed with delivery failures");
+        });
+    };
+    function operation(name, callbackOrOptions, options) {
+        const args = splitOperationArgs(callbackOrOptions, options);
+        if (finished || completionRequested) {
+            const ignored = {
+                operationId: globalThis.crypto.randomUUID(),
+                done: () => undefined,
+                fail: () => undefined,
+            };
+            return args.callback === undefined
+                ? ignored
+                : withOperationCallback(ignored, args.callback);
+        }
+        const handle = flow.operation(name, args.options);
+        activeOperations.add(handle.operationId);
+        let closed = false;
+        const operationHandle = {
+            operationId: handle.operationId,
+            done: () => {
+                if (finished || closed) {
+                    return;
+                }
+                closed = true;
+                activeOperations.delete(handle.operationId);
+                handle.done();
+                if (completionRequested && activeOperations.size === 0) {
+                    finish(() => undefined);
+                }
+            },
+            fail: (failure) => {
+                if (finished || closed) {
+                    return;
+                }
+                closed = true;
+                activeOperations.delete(handle.operationId);
+                handle.fail(failure);
+                if (completionRequested && activeOperations.size === 0) {
+                    finish(() => undefined);
+                }
+            },
+        };
+        return args.callback === undefined
+            ? operationHandle
+            : withOperationCallback(operationHandle, args.callback);
+    }
+    return {
+        runId: flow.runId,
+        step(name, stepOptions) {
+            if (!finished && !completionRequested) {
+                flow.step(name, stepOptions);
+            }
+        },
+        done: (options) => {
+            if (finished || completionRequested) {
+                return;
+            }
+            if (activeOperations.size > 0) {
+                completionRequested = true;
+                flow.done(options);
+                return;
+            }
+            finish(() => flow.done(options));
+        },
+        fail: (options) => finish(() => flow.fail(options)),
+        error: (error) => {
+            if (!finished && !completionRequested) {
+                flow.error(error);
+            }
+        },
+        setProperties: (properties) => {
+            if (!finished && !completionRequested) {
+                flow.setProperties(properties);
+            }
+        },
+        operation,
+        progress: (progress) => {
+            if (!finished && !completionRequested) {
+                flow.progress(progress);
+            }
+        },
+    };
+}

package/dist/client/runtime.d.ts

@@ -0,0 +1,5 @@
+import { Layer } from "effect";
+import { WorkflowTransport } from "../features/delivery/ports/workflow-transport.js";
+import type { FlowmarkClient, InstrumentationErrorHandler, WorkflowRunOptions } from "../types/index.js";
+/** Shared execution boundary; this module has no Node.js or framework imports. */
+export declare function makeClient(transport: Layer.Layer<WorkflowTransport>, onError?: InstrumentationErrorHandler, defaults?: Pick<WorkflowRunOptions, "environment" | "release">): FlowmarkClient;

package/dist/client/runtime.js

@@ -0,0 +1,72 @@
+import { Effect, Layer, ManagedRuntime } from "effect";
+import { FlowmarkConfigError } from "../errors/index.js";
+import { DeliveryQueue } from "../features/delivery/delivery-queue.js";
+import { WorkflowEngine } from "../features/workflows/workflow-engine.js";
+import { withOperationCallback } from "../utils/operation-callback.js";
+import { splitOperationArgs } from "../utils/operation-args.js";
+/** Shared execution boundary; this module has no Node.js or framework imports. */
+export function makeClient(transport, onError, defaults = {}) {
+    const delivery = DeliveryQueue.layer(onError).pipe(Layer.provide(transport));
+    const runtime = ManagedRuntime.make(WorkflowEngine.layer.pipe(Layer.provideMerge(delivery)));
+    const engine = runtime.runSync(WorkflowEngine);
+    const queue = runtime.runSync(DeliveryQueue);
+    let shutdownResult;
+    const runMarker = (command) => {
+        if (shutdownResult) {
+            console.warn("[Flowmark] Ignored workflow marker after client shutdown");
+            return;
+        }
+        runtime.runSync(command);
+    };
+    return {
+        workflow(name, options = {}) {
+            if (shutdownResult) {
+                throw new FlowmarkConfigError({ cause: "Client has been shut down" });
+            }
+            const handle = runtime.runSync(engine.start(name, {
+                ...defaults,
+                ...options,
+                environment: options.environment ?? defaults.environment,
+                release: options.release ?? defaults.release,
+            }));
+            function operation(name, callbackOrOptions, options) {
+                const args = splitOperationArgs(callbackOrOptions, options);
+                const effectHandle = shutdownResult
+                    ? {
+                        operationId: globalThis.crypto.randomUUID(),
+                        done: Effect.void,
+                        fail: () => Effect.void,
+                    }
+                    : runtime.runSync(handle.operation(name, args.options));
+                const operationHandle = {
+                    operationId: effectHandle.operationId,
+                    done: () => runMarker(effectHandle.done),
+                    fail: (failure) => runMarker(effectHandle.fail(failure)),
+                };
+                if (args.callback === undefined) {
+                    return operationHandle;
+                }
+                return withOperationCallback(operationHandle, args.callback);
+            }
+            return {
+                runId: handle.runId,
+                step: (name, stepOptions) => runMarker(handle.step(name, stepOptions)),
+                done: (doneOptions) => runMarker(handle.done(doneOptions)),
+                fail: (options) => runMarker(handle.fail(options)),
+                error: (error) => runMarker(handle.error(error)),
+                setProperties: (properties) => runMarker(handle.setProperties(properties)),
+                operation,
+                progress: (progress) => runMarker(handle.progress(progress)),
+            };
+        },
+        flush() {
+            return shutdownResult ?? runtime.runPromise(queue.flush);
+        },
+        shutdown() {
+            shutdownResult ??= runtime
+                .runPromise(queue.shutdown)
+                .finally(() => runtime.dispose());
+            return shutdownResult;
+        },
+    };
+}

package/dist/config/api-origin.d.ts

@@ -0,0 +1,2 @@
+import { Schema } from "effect";
+export declare const ApiOriginSchema: Schema.filter<typeof Schema.String>;

package/dist/config/api-origin.js

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+export const ApiOriginSchema = Schema.String.pipe(Schema.filter((value) => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" ||
+            (url.protocol === "http:" &&
+                ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}));

package/dist/config/define-config.d.ts

@@ -0,0 +1,11 @@
+import type { FlowmarkConfig } from "../types/index.js";
+/**
+ * Defines server configuration with autocomplete and preserved literal types.
+ * Returns the same object without reading environment variables, validating credentials,
+ * creating a client, or starting delivery. Validation happens at the client boundary.
+ * Export from flowmark.config.ts and pass to createFlowmark(); the file is not auto-loaded.
+ * Keep this configuration server-only. Use @flowmarkdev/node/browser for public browser keys.
+ * @example
+ * export default defineConfig({ apiUrl: "http://localhost:3003" })
+ */
+export declare function defineConfig<const T extends FlowmarkConfig>(config: T & Record<Exclude<keyof T, keyof FlowmarkConfig>, never>): T;

package/dist/config/define-config.js

@@ -0,0 +1,12 @@
+/**
+ * Defines server configuration with autocomplete and preserved literal types.
+ * Returns the same object without reading environment variables, validating credentials,
+ * creating a client, or starting delivery. Validation happens at the client boundary.
+ * Export from flowmark.config.ts and pass to createFlowmark(); the file is not auto-loaded.
+ * Keep this configuration server-only. Use @flowmarkdev/node/browser for public browser keys.
+ * @example
+ * export default defineConfig({ apiUrl: "http://localhost:3003" })
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/settings.d.ts

@@ -0,0 +1,11 @@
+import { Context, Redacted } from "effect";
+import type { FlowmarkConfig } from "../types/index.js";
+export interface FlowmarkSettingsService {
+    readonly apiKey: Redacted.Redacted<string>;
+    readonly apiUrl: string;
+}
+declare const FlowmarkSettings_base: Context.TagClass<FlowmarkSettings, "@flowmarkdev/node/Settings", FlowmarkSettingsService>;
+export declare class FlowmarkSettings extends FlowmarkSettings_base {
+}
+export declare function resolveSettings(config: FlowmarkConfig): FlowmarkSettingsService;
+export {};

package/dist/config/settings.js

@@ -0,0 +1,31 @@
+import { Context, Either, Redacted, Schema } from "effect";
+import { FlowmarkConfigError } from "../errors/index.js";
+import { ApiOriginSchema } from "./api-origin.js";
+const SettingsSchema = Schema.Struct({
+    apiKey: Schema.RedactedFromSelf(Schema.String.pipe(Schema.minLength(1))),
+    apiUrl: ApiOriginSchema,
+});
+export class FlowmarkSettings extends Context.Tag("@flowmarkdev/node/Settings")() {
+}
+export function resolveSettings(config) {
+    const apiKey = config.apiKey ?? process.env.FLOWMARK_API_KEY;
+    if (!apiKey) {
+        throw new FlowmarkConfigError({
+            cause: "A server write key is required. Set FLOWMARK_API_KEY in the server environment or pass apiKey to createFlowmark(). For the local repository demo, run pnpm dev:setup first. Never put a server key in browser configuration.",
+        });
+    }
+    const decoded = Schema.decodeUnknownEither(SettingsSchema)({
+        apiKey: apiKey === undefined ? undefined : Redacted.make(apiKey),
+        apiUrl: config.apiUrl ??
+            process.env.FLOWMARK_API_URL ??
+            (process.env.NODE_ENV !== "production"
+                ? "http://localhost:3003"
+                : undefined),
+    });
+    return Either.match(decoded, {
+        onLeft: (cause) => {
+            throw new FlowmarkConfigError({ cause });
+        },
+        onRight: (settings) => settings,
+    });
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,49 @@
+import { type Cause } from "effect";
+import type { WorkflowEvent, WorkflowEventValidationError } from "@flowmarkdev/core";
+declare const FlowmarkConfigError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "FlowmarkConfigError";
+} & Readonly<A>;
+/** Invalid credentials/origin, unsupported execution context, or use of a closed client. */
+export declare class FlowmarkConfigError extends FlowmarkConfigError_base<{
+    readonly cause: unknown;
+}> {
+    get message(): string;
+}
+declare const FlowmarkHttpError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "FlowmarkHttpError";
+} & Readonly<A>;
+/** HTTP delivery failure; status is undefined for encoding, network, or timeout failures. Preserves the original cause. */
+export declare class FlowmarkHttpError extends FlowmarkHttpError_base<{
+    readonly status: number | undefined;
+    readonly cause: unknown;
+}> {
+}
+declare const WorkflowTransportError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkflowTransportError";
+} & Readonly<A>;
+/** Associates a failed event with its Effect Cause, including original transport failures/defects. */
+export declare class WorkflowTransportError extends WorkflowTransportError_base<{
+    readonly event: WorkflowEvent;
+    readonly cause: Cause.Cause<unknown>;
+}> {
+}
+declare const FlowmarkQueueError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "FlowmarkQueueError";
+} & Readonly<A>;
+/** An event could not be queued because the 1,000-event limit was reached or delivery was closed. */
+export declare class FlowmarkQueueError extends FlowmarkQueueError_base<{
+    readonly event: WorkflowEvent;
+    readonly reason: "capacity" | "closed";
+}> {
+}
+/** Failures reported to onInstrumentationError or collected by flush()/shutdown(). */
+export type DeliveryFailure = WorkflowTransportError | WorkflowEventValidationError | FlowmarkQueueError;
+declare const FlowmarkDeliveryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "FlowmarkDeliveryError";
+} & Readonly<A>;
+/** Rejection from flush()/shutdown(). The failures array preserves each reported delivery/validation error. */
+export declare class FlowmarkDeliveryError extends FlowmarkDeliveryError_base<{
+    readonly failures: ReadonlyArray<DeliveryFailure>;
+}> {
+}
+export {};

package/dist/errors/index.js

@@ -0,0 +1,21 @@
+import { Data } from "effect";
+/** Invalid credentials/origin, unsupported execution context, or use of a closed client. */
+export class FlowmarkConfigError extends Data.TaggedError("FlowmarkConfigError") {
+    get message() {
+        return typeof this.cause === "string"
+            ? this.cause
+            : "Invalid Flowmark configuration. Check the API URL and server credentials; see the original cause for validation details.";
+    }
+}
+/** HTTP delivery failure; status is undefined for encoding, network, or timeout failures. Preserves the original cause. */
+export class FlowmarkHttpError extends Data.TaggedError("FlowmarkHttpError") {
+}
+/** Associates a failed event with its Effect Cause, including original transport failures/defects. */
+export class WorkflowTransportError extends Data.TaggedError("WorkflowTransportError") {
+}
+/** An event could not be queued because the 1,000-event limit was reached or delivery was closed. */
+export class FlowmarkQueueError extends Data.TaggedError("FlowmarkQueueError") {
+}
+/** Rejection from flush()/shutdown(). The failures array preserves each reported delivery/validation error. */
+export class FlowmarkDeliveryError extends Data.TaggedError("FlowmarkDeliveryError") {
+}

package/dist/features/delivery/adapters/http-transport.d.ts

@@ -0,0 +1,8 @@
+import { HttpClient } from "@effect/platform";
+import { Effect, type Redacted } from "effect";
+import { WorkflowTransport } from "../ports/workflow-transport.js";
+export interface HttpTransportOptions {
+    readonly endpoint: string;
+    readonly apiKey?: Redacted.Redacted<string>;
+}
+export declare const makeHttpTransport: (settings: HttpTransportOptions) => Effect.Effect<WorkflowTransport, never, HttpClient.HttpClient>;

package/dist/features/delivery/adapters/http-transport.js

@@ -0,0 +1,31 @@
+import { HttpClient, HttpClientRequest } from "@effect/platform";
+import { Effect, Match, Schedule } from "effect";
+import { FlowmarkHttpError } from "../../../errors/index.js";
+import { WorkflowTransport } from "../ports/workflow-transport.js";
+export const makeHttpTransport = Effect.fn("Flowmark.HttpTransport.make")(function* (settings) {
+    const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk, HttpClient.withScope);
+    const emit = Effect.fn("Flowmark.HttpTransport.emit")(function* (event) {
+        const eventId = yield* Effect.sync(() => globalThis.crypto.randomUUID());
+        // Build once so all retries carry the same idempotency key and payload.
+        const baseRequest = HttpClientRequest.post(settings.endpoint);
+        const request = yield* (settings.apiKey
+            ? baseRequest.pipe(HttpClientRequest.bearerToken(settings.apiKey))
+            : baseRequest).pipe(HttpClientRequest.bodyJson({ eventId, event }), Effect.mapError((cause) => new FlowmarkHttpError({ status: undefined, cause })));
+        yield* Effect.scoped(client.execute(request)).pipe(Effect.mapError((cause) => new FlowmarkHttpError({
+            status: Match.value(cause).pipe(Match.tag("ResponseError", ({ response }) => response.status), Match.tag("RequestError", () => undefined), Match.exhaustive),
+            cause,
+        })), Effect.timeoutFail({
+            duration: "3 seconds",
+            onTimeout: () => new FlowmarkHttpError({
+                status: undefined,
+                cause: "Ingestion timed out",
+            }),
+        }), Effect.retry({
+            schedule: Schedule.exponential("100 millis").pipe(Schedule.intersect(Schedule.recurs(2))),
+            while: (error) => error.status === undefined ||
+                error.status === 429 ||
+                error.status >= 500,
+        }));
+    });
+    return WorkflowTransport.of({ emit });
+});

package/dist/features/delivery/adapters/http.d.ts

@@ -0,0 +1,4 @@
+import { Layer } from "effect";
+import { FlowmarkSettings } from "../../../config/settings.js";
+import { WorkflowTransport } from "../ports/workflow-transport.js";
+export declare const HttpTransportLive: Layer.Layer<WorkflowTransport, never, FlowmarkSettings | import("@effect/platform/HttpClient").HttpClient>;

package/dist/features/delivery/adapters/http.js

@@ -0,0 +1,11 @@
+import { Effect, Layer } from "effect";
+import { FlowmarkSettings } from "../../../config/settings.js";
+import { WorkflowTransport } from "../ports/workflow-transport.js";
+import { makeHttpTransport } from "./http-transport.js";
+export const HttpTransportLive = Layer.effect(WorkflowTransport, Effect.gen(function* () {
+    const settings = yield* FlowmarkSettings;
+    return yield* makeHttpTransport({
+        endpoint: new URL("/v1/events", settings.apiUrl).toString(),
+        apiKey: settings.apiKey,
+    });
+}));

package/dist/features/delivery/adapters/memory-transport.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { WorkflowEvent } from "@flowmarkdev/core";
+import type { WorkflowTransport } from "../ports/workflow-transport.js";
+/** In-memory transport for tests/custom integrations. Nothing is sent to the Flowmark API. */
+export declare class MemoryTransport implements WorkflowTransport {
+    /** Successfully emitted events in delivery order. Not persisted across process restarts. */
+    readonly events: WorkflowEvent[];
+    /** Returns a lazy Effect that appends an event when executed. */
+    emit(event: WorkflowEvent): Effect.Effect<void>;
+}

package/dist/features/delivery/adapters/memory-transport.js

@@ -0,0 +1,12 @@
+import { Effect } from "effect";
+/** In-memory transport for tests/custom integrations. Nothing is sent to the Flowmark API. */
+export class MemoryTransport {
+    /** Successfully emitted events in delivery order. Not persisted across process restarts. */
+    events = [];
+    /** Returns a lazy Effect that appends an event when executed. */
+    emit(event) {
+        return Effect.sync(() => {
+            this.events.push(event);
+        });
+    }
+}

package/dist/features/delivery/delivery-queue.d.ts

@@ -0,0 +1,15 @@
+import { Context, Effect, Layer } from "effect";
+import { type WorkflowEvent } from "@flowmarkdev/core";
+import { FlowmarkDeliveryError } from "../../errors/index.js";
+import type { InstrumentationErrorHandler } from "../../types/index.js";
+import { WorkflowTransport } from "./ports/workflow-transport.js";
+export interface DeliveryQueueService {
+    readonly enqueue: (event: WorkflowEvent, ordering: Effect.Semaphore) => Effect.Effect<void>;
+    readonly flush: Effect.Effect<void, FlowmarkDeliveryError>;
+    readonly shutdown: Effect.Effect<void, FlowmarkDeliveryError>;
+}
+declare const DeliveryQueue_base: Context.TagClass<DeliveryQueue, "@flowmarkdev/node/DeliveryQueue", DeliveryQueueService>;
+export declare class DeliveryQueue extends DeliveryQueue_base {
+    static layer(onError?: InstrumentationErrorHandler): Layer.Layer<DeliveryQueue, never, WorkflowTransport>;
+}
+export {};

package/dist/features/delivery/delivery-queue.js

@@ -0,0 +1,56 @@
+import { Context, Effect, FiberSet, Layer, Ref } from "effect";
+import { decodeWorkflowEvent } from "@flowmarkdev/core";
+import { FlowmarkDeliveryError, FlowmarkQueueError, WorkflowTransportError, } from "../../errors/index.js";
+import { WorkflowTransport } from "./ports/workflow-transport.js";
+export class DeliveryQueue extends Context.Tag("@flowmarkdev/node/DeliveryQueue")() {
+    static layer(onError) {
+        return Layer.scoped(DeliveryQueue, Effect.gen(function* () {
+            const transport = yield* WorkflowTransport;
+            const pending = yield* FiberSet.make();
+            const failures = yield* Ref.make([]);
+            const closed = yield* Ref.make(false);
+            const queueAccess = yield* Effect.makeSemaphore(1);
+            const report = Effect.fn("Flowmark.DeliveryQueue.report")(function* (error, event) {
+                yield* Ref.update(failures, (errors) => [...errors, error]);
+                if (onError) {
+                    yield* Effect.sync(() => onError(error, event)).pipe(Effect.catchAllCause(() => Effect.logWarning("[Flowmark] Instrumentation error callback failed")));
+                }
+                else {
+                    yield* Effect.logWarning(`[Flowmark] Could not deliver ${event.type} for ${event.workflow}`, {
+                        error: error._tag,
+                    });
+                }
+            });
+            const deliver = Effect.fn("Flowmark.DeliveryQueue.deliver")(function* (event) {
+                const decoded = yield* decodeWorkflowEvent(event);
+                yield* transport
+                    .emit(decoded)
+                    .pipe(Effect.catchAllCause((cause) => Effect.fail(new WorkflowTransportError({ event: decoded, cause }))));
+            });
+            const enqueue = Effect.fn("Flowmark.DeliveryQueue.enqueue")(function* (event, ordering) {
+                const isClosed = yield* Ref.get(closed);
+                if (isClosed || (yield* FiberSet.size(pending)) >= 1000) {
+                    return yield* report(new FlowmarkQueueError({
+                        event,
+                        reason: isClosed ? "closed" : "capacity",
+                    }), event);
+                }
+                yield* FiberSet.run(pending, ordering.withPermits(1)(deliver(event).pipe(Effect.catchAll((error) => report(error, event)), Effect.catchAllCause((cause) => report(new WorkflowTransportError({ event, cause }), event)))));
+            }, queueAccess.withPermits(1), Effect.asVoid);
+            const flush = Effect.gen(function* () {
+                yield* FiberSet.awaitEmpty(pending);
+                const errors = yield* Ref.getAndSet(failures, []);
+                if (errors.length > 0) {
+                    return yield* Effect.fail(new FlowmarkDeliveryError({ failures: errors }));
+                }
+            });
+            return DeliveryQueue.of({
+                enqueue,
+                flush,
+                shutdown: queueAccess
+                    .withPermits(1)(Ref.set(closed, true))
+                    .pipe(Effect.andThen(flush)),
+            });
+        }));
+    }
+}

package/dist/features/delivery/ports/workflow-transport.d.ts

@@ -0,0 +1,9 @@
+import { Context, type Effect } from "effect";
+import type { WorkflowEvent } from "@flowmarkdev/core";
+/** Port for delivering validated workflow events to an external destination. */
+export interface WorkflowTransport {
+    /** Returns a lazy delivery Effect. Expected failures use the Effect error channel. */
+    readonly emit: (event: WorkflowEvent) => Effect.Effect<void, Error>;
+}
+/** Effect dependency tag for replacing delivery implementations. */
+export declare const WorkflowTransport: Context.Tag<WorkflowTransport, WorkflowTransport>;

package/dist/features/delivery/ports/workflow-transport.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+/** Effect dependency tag for replacing delivery implementations. */
+export const WorkflowTransport = Context.GenericTag("@flowmarkdev/node/WorkflowTransport");

package/dist/features/workflows/workflow-engine.d.ts

@@ -0,0 +1,27 @@
+import { Context, Effect, Layer } from "effect";
+import type { WorkflowError, WorkflowName, WorkflowOperationFailure, WorkflowProperties, WorkflowProgress, WorkflowStepName } from "@flowmarkdev/core";
+import type { WorkflowDoneOptions, WorkflowFailOptions, WorkflowOperationOptions, WorkflowRunOptions, WorkflowStepOptions } from "../../types/index.js";
+import { DeliveryQueue } from "../delivery/delivery-queue.js";
+export interface WorkflowOperationHandle {
+    readonly operationId: string;
+    readonly done: Effect.Effect<void>;
+    readonly fail: (failure: WorkflowOperationFailure) => Effect.Effect<void>;
+}
+export interface WorkflowHandle {
+    readonly runId: string;
+    readonly step: (name: WorkflowStepName, options?: WorkflowStepOptions) => Effect.Effect<void>;
+    readonly done: (options?: WorkflowDoneOptions) => Effect.Effect<void>;
+    readonly fail: (options: WorkflowFailOptions) => Effect.Effect<void>;
+    readonly error: (error: WorkflowError) => Effect.Effect<void>;
+    readonly setProperties: (properties: WorkflowProperties) => Effect.Effect<void>;
+    readonly operation: (name: WorkflowStepName, options?: WorkflowOperationOptions) => Effect.Effect<WorkflowOperationHandle>;
+    readonly progress: (progress: WorkflowProgress) => Effect.Effect<void>;
+}
+export interface WorkflowEngineService {
+    readonly start: (name: WorkflowName, options: WorkflowRunOptions) => Effect.Effect<WorkflowHandle>;
+}
+declare const WorkflowEngine_base: Context.TagClass<WorkflowEngine, "@flowmarkdev/node/WorkflowEngine", WorkflowEngineService>;
+export declare class WorkflowEngine extends WorkflowEngine_base {
+    static readonly layer: Layer.Layer<WorkflowEngine, never, DeliveryQueue>;
+}
+export {};