@voyant-travel/workflows 0.107.10

package/dist/client.js

@@ -0,0 +1,305 @@
+// Client-safe workflow API for app/server code that triggers or forwards
+// workflow activity to a managed Voyant Cloud runtime.
+const DEFAULT_ENVIRONMENT = "production";
+let configuredClient;
+/**
+ * Install the process-local `workflows` client implementation used by the
+ * root `@voyant-travel/workflows` singleton. Apps may call this during boot, or
+ * rely on deployment-injected Voyant Cloud environment variables.
+ */
+export function configureWorkflowsClient(client) {
+    configuredClient = client;
+}
+export function getConfiguredWorkflowsClient() {
+    return configuredClient;
+}
+export const workflows = new Proxy({}, {
+    get(_, method) {
+        return (...args) => {
+            const client = configuredClient ?? tryCreateCloudClientFromEnv();
+            if (!client) {
+                throw new Error(`@voyant-travel/workflows: workflows.${method}() requires a configured workflows client. ` +
+                    `Use configureWorkflowsClient(createCloudWorkflowsClient(...)) or provide the ` +
+                    `VOYANT_CLOUD_WORKFLOWS_URL, VOYANT_CLOUD_WORKFLOW_TRIGGER_TOKEN, ` +
+                    `VOYANT_CLOUD_APP_SLUG, and VOYANT_CLOUD_ENVIRONMENT deployment variables.`);
+            }
+            const fn = client[method];
+            if (typeof fn !== "function") {
+                throw new Error(`@voyant-travel/workflows: workflows.${method} is not implemented`);
+            }
+            return fn(...args);
+        };
+    },
+});
+export function createCloudWorkflowsClient(options = {}) {
+    const config = resolveCloudConfig(options);
+    const httpFetch = options.fetch ?? globalThis.fetch;
+    if (typeof httpFetch !== "function") {
+        throw new Error("@voyant-travel/workflows/client: global fetch is unavailable");
+    }
+    return {
+        async trigger(workflow, input, opts) {
+            const workflowId = workflowIdOf(workflow);
+            const environment = opts?.environment ?? config.environment;
+            const res = await cloudFetch(httpFetch, config, {
+                method: "POST",
+                path: `/apps/${encodeURIComponent(config.appSlug)}/${environment}/workflows/${encodeURIComponent(workflowId)}/runs`,
+                body: {
+                    input,
+                    options: serializeTriggerOptions(opts),
+                },
+                idempotencyKey: opts?.idempotencyKey,
+            });
+            return normalizeRun(await readJson(res), workflowId);
+        },
+        signal() {
+            return unsupported("signal");
+        },
+        completeToken() {
+            return unsupported("completeToken");
+        },
+        cancel() {
+            return unsupported("cancel");
+        },
+        retry() {
+            return unsupported("retry");
+        },
+        replay() {
+            return unsupported("replay");
+        },
+        get() {
+            return unsupported("get");
+        },
+        list() {
+            return unsupported("list");
+        },
+        mintAccessToken() {
+            return unsupported("mintAccessToken");
+        },
+    };
+}
+/**
+ * Cloud-mode driver for framework event forwarding. It does not execute runs
+ * locally; it forwards triggers/events/manifests to the hosted runtime using
+ * the same deployment-scoped credentials as the client.
+ */
+export function createCloudWorkflowDriver(options = {}) {
+    const client = createCloudWorkflowsClient(options);
+    const config = resolveCloudConfig(options);
+    const httpFetch = options.fetch ?? globalThis.fetch;
+    const manifestRegistration = options.manifestRegistration ?? "disabled";
+    return {
+        async registerManifest(args) {
+            if (manifestRegistration === "disabled") {
+                return { versionId: args.manifest.versionId };
+            }
+            const res = await cloudFetch(httpFetch, config, {
+                method: "POST",
+                path: `/apps/${encodeURIComponent(config.appSlug)}/${args.environment}/workflow-releases`,
+                body: { manifest: args.manifest },
+            });
+            const body = await readJson(res);
+            return {
+                versionId: readString(body, ["versionId"]) ??
+                    readString(body, ["data", "versionId"]) ??
+                    args.manifest.versionId,
+            };
+        },
+        trigger(workflow, input, opts) {
+            return client.trigger(workflow, input, opts);
+        },
+        async ingestEvent(args) {
+            const eventId = typeof args.envelope.metadata?.eventId === "string"
+                ? args.envelope.metadata.eventId
+                : args.idempotencyKey;
+            const res = await cloudFetch(httpFetch, config, {
+                method: "POST",
+                path: `/apps/${encodeURIComponent(config.appSlug)}/${args.environment}/events`,
+                body: {
+                    envelope: args.envelope,
+                    idempotencyKey: args.idempotencyKey,
+                },
+                idempotencyKey: eventId,
+            });
+            return (await readJson(res));
+        },
+        async getManifest(args) {
+            const res = await cloudFetch(httpFetch, config, {
+                method: "GET",
+                path: `/apps/${encodeURIComponent(config.appSlug)}/${args.environment}/workflow-releases/current`,
+                allowStatuses: [404],
+            });
+            if (res.status === 404)
+                return null;
+            const body = await readJson(res);
+            return (readRecord(body, ["manifest"]) ??
+                readRecord(body, ["data", "manifest"]) ??
+                body);
+        },
+    };
+}
+function tryCreateCloudClientFromEnv() {
+    const env = defaultEnv();
+    if (!env.VOYANT_CLOUD_WORKFLOWS_URL ||
+        !env.VOYANT_CLOUD_WORKFLOW_TRIGGER_TOKEN ||
+        !env.VOYANT_CLOUD_APP_SLUG) {
+        return undefined;
+    }
+    const client = createCloudWorkflowsClient({ env });
+    configuredClient = client;
+    return client;
+}
+function resolveCloudConfig(options) {
+    const env = { ...defaultEnv(), ...options.env };
+    const baseUrl = options.baseUrl ?? env.VOYANT_CLOUD_WORKFLOWS_URL;
+    const triggerToken = options.triggerToken ?? env.VOYANT_CLOUD_WORKFLOW_TRIGGER_TOKEN;
+    const appSlug = options.appSlug ?? env.VOYANT_CLOUD_APP_SLUG;
+    const environment = parseEnvironment(options.environment ?? env.VOYANT_CLOUD_ENVIRONMENT ?? DEFAULT_ENVIRONMENT);
+    const missing = [
+        ["baseUrl", baseUrl],
+        ["triggerToken", triggerToken],
+        ["appSlug", appSlug],
+    ]
+        .filter(([, value]) => !value)
+        .map(([name]) => name);
+    if (missing.length > 0) {
+        throw new Error(`@voyant-travel/workflows/client: missing Cloud workflow configuration: ${missing.join(", ")}`);
+    }
+    return {
+        baseUrl: stripTrailingSlash(requireConfigValue(baseUrl, "baseUrl")),
+        triggerToken: requireConfigValue(triggerToken, "triggerToken"),
+        appSlug: requireConfigValue(appSlug, "appSlug"),
+        environment,
+    };
+}
+function requireConfigValue(value, name) {
+    if (!value) {
+        throw new Error(`@voyant-travel/workflows/client: missing Cloud workflow configuration: ${name}`);
+    }
+    return value;
+}
+async function cloudFetch(httpFetch, config, args) {
+    const headers = new Headers({
+        accept: "application/json",
+        authorization: `Bearer ${config.triggerToken}`,
+    });
+    if (args.body !== undefined)
+        headers.set("content-type", "application/json");
+    if (args.idempotencyKey)
+        headers.set("idempotency-key", args.idempotencyKey);
+    const res = await httpFetch(`${config.baseUrl}/cloud/v1${args.path}`, {
+        method: args.method,
+        headers,
+        body: args.body === undefined ? undefined : JSON.stringify(args.body),
+    });
+    if (!res.ok && !args.allowStatuses?.includes(res.status)) {
+        throw new Error(`Voyant Cloud workflows request failed: ${res.status} ${res.statusText} ${await res.text()}`);
+    }
+    return res;
+}
+async function readJson(res) {
+    const text = await res.text();
+    if (text.length === 0)
+        return {};
+    return JSON.parse(text);
+}
+function normalizeRun(body, fallbackWorkflowId) {
+    const source = readRecord(body, ["data", "run"]) ??
+        readRecord(body, ["run"]) ??
+        readRecord(body, ["data"]) ??
+        asRecord(body);
+    const id = readString(source, ["id"]) ?? readString(source, ["runId"]);
+    if (!id) {
+        throw new Error("Voyant Cloud workflows response did not include a run id");
+    }
+    return {
+        id,
+        workflowId: readString(source, ["workflowId"]) ??
+            readString(source, ["workflow", "id"]) ??
+            fallbackWorkflowId,
+        status: parseRunStatus(readString(source, ["status"]) ?? "pending"),
+        startedAt: readNumber(source, ["startedAt"]) ?? Date.now(),
+        accessToken: readString(source, ["accessToken"]),
+    };
+}
+function serializeTriggerOptions(opts) {
+    if (!opts)
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(opts)) {
+        if (value === undefined || key === "environment")
+            continue;
+        out[key] = value instanceof Date ? value.toISOString() : value;
+    }
+    return out;
+}
+function workflowIdOf(workflow) {
+    return typeof workflow === "string" ? workflow : workflow.id;
+}
+function unsupported(method) {
+    throw new Error(`@voyant-travel/workflows/client: workflows.${method}() is not supported by the ` +
+        `managed Cloud trigger client yet.`);
+}
+function defaultEnv() {
+    const processEnv = globalThis.process?.env;
+    return processEnv ?? {};
+}
+function parseEnvironment(value) {
+    if (value === "production" || value === "preview" || value === "development")
+        return value;
+    throw new Error(`@voyant-travel/workflows/client: invalid environment "${value}"; expected production, preview, or development`);
+}
+function parseRunStatus(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === "pending" ||
+        normalized === "queued" ||
+        normalized === "running" ||
+        normalized === "waiting" ||
+        normalized === "completed" ||
+        normalized === "failed" ||
+        normalized === "cancelled" ||
+        normalized === "cancelled_by_dev_reload" ||
+        normalized === "cancelled_by_version_sunset" ||
+        normalized === "compensated" ||
+        normalized === "compensation_failed" ||
+        normalized === "timed_out") {
+        return normalized;
+    }
+    return "pending";
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function readRecord(value, path) {
+    const current = readAtPath(value, path);
+    return typeof current === "object" && current !== null
+        ? current
+        : undefined;
+}
+function readString(value, path) {
+    const current = readAtPath(value, path);
+    return typeof current === "string" && current.length > 0 ? current : undefined;
+}
+function readNumber(value, path) {
+    const current = readAtPath(value, path);
+    if (typeof current === "number")
+        return current;
+    if (typeof current === "string" && current.length > 0) {
+        const parsed = Number(current);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function readAtPath(value, path) {
+    let current = value;
+    for (const part of path) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}

package/dist/conditions.d.ts

@@ -0,0 +1,29 @@
+import type { Duration, RunStatus } from "./types.js";
+export interface EventCondition {
+    event: string;
+    match?: Record<string, unknown> | ((payload: unknown) => boolean);
+}
+export interface SignalCondition {
+    signal: string;
+    match?: Record<string, unknown> | ((payload: unknown) => boolean);
+}
+export interface TimeCondition {
+    after?: Duration | Date;
+    before?: Duration | Date;
+}
+export interface RunStatusCondition {
+    run: {
+        id: string;
+        status: RunStatus[];
+    };
+}
+export interface OrCondition {
+    or: Condition[];
+}
+export interface AndCondition {
+    and: Condition[];
+}
+export type Condition = EventCondition | SignalCondition | TimeCondition | RunStatusCondition | OrCondition | AndCondition;
+export declare const or: (...conditions: Condition[]) => OrCondition;
+export declare const and: (...conditions: Condition[]) => AndCondition;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAErD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,EAAE,CAAA;KAAE,CAAA;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,SAAS,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,EAAE,CAAA;CACjB;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,eAAe,GACf,aAAa,GACb,kBAAkB,GAClB,WAAW,GACX,YAAY,CAAA;AAEhB,eAAO,MAAM,EAAE,GAAI,GAAG,YAAY,SAAS,EAAE,KAAG,WAAmC,CAAA;AACnF,eAAO,MAAM,GAAG,GAAI,GAAG,YAAY,SAAS,EAAE,KAAG,YAAqC,CAAA"}

package/dist/conditions.js

@@ -0,0 +1,5 @@
+// Condition types used in step options (waitFor / cancelIf / skipIf)
+// and in event-filter match expressions.
+// Authoritative contract in docs/sdk-surface.md §4.
+export const or = (...conditions) => ({ or: conditions });
+export const and = (...conditions) => ({ and: conditions });

package/dist/config.d.ts

@@ -0,0 +1,93 @@
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
+/** Cloudflare Container instance types — see `@voyant-travel/workflows` for the size table. */
+export type MachineType = "lite" | "basic" | "standard-1" | "standard-2" | "standard-3" | "standard-4" | (string & {});
+export type EnvironmentName = "production" | "preview" | "development";
+export type MeterKey = "edgeCpuMs" | "containerSeconds" | "warmSlotHours" | "runCount" | "activeScheduleHours" | "payloadStorageGbHour" | "retentionRunMonths";
+export type BindingDeclaration = {
+    type: "d1";
+    name: string;
+} | {
+    type: "r2";
+    name: string;
+} | {
+    type: "kv";
+    name: string;
+} | {
+    type: "queue";
+    name: string;
+};
+export interface EnvironmentConfig {
+    customDomain?: string;
+}
+export interface RetryPolicy {
+    max?: number;
+    backoff?: "exponential" | "linear" | "fixed";
+    initial?: Duration;
+    maxDelay?: Duration;
+}
+export interface BuildExtension {
+    name: string;
+    /** Open-ended hook surface; each extension defines its own contract. */
+    [key: string]: unknown;
+}
+export interface Instrumentation {
+    name: string;
+    [key: string]: unknown;
+}
+export interface WorkflowsConfig {
+    dirs?: string[];
+    defaults?: {
+        retries?: RetryPolicy;
+        timeout?: Duration;
+        timezone?: string;
+        machine?: MachineType;
+        concurrency?: {
+            strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin";
+        };
+    };
+    containerPool?: {
+        defaultMachine?: MachineType;
+        maxConcurrency?: number;
+        warmPoolSize?: Partial<Record<EnvironmentName, number>>;
+        evictionTtl?: Duration;
+        perPodConcurrency?: number;
+        scaleOutPolicy?: "none" | "onDemand";
+        preWarmStrategy?: "onFirstRequest" | "onDeploy";
+    };
+    build?: {
+        extensions?: BuildExtension[];
+        defineEnv?: Record<string, string>;
+    };
+    instrumentations?: Instrumentation[];
+    dev?: {
+        port?: number;
+        preservation?: "smart" | "always" | "never";
+        simulateEnvironment?: EnvironmentName;
+    };
+    billing?: {
+        caps?: {
+            monthly?: Partial<Record<MeterKey, number>>;
+            action?: "hard-stop" | "soft-notify";
+            perEnvironment?: Partial<Record<EnvironmentName, {
+                monthly?: Partial<Record<MeterKey, number>>;
+            }>>;
+        };
+    };
+    versioning?: {
+        retireAfter?: Duration;
+        onSunset?: "cancel" | "migrate" | "extend";
+        sunsetNoticePeriod?: Duration;
+    };
+}
+export interface VoyantConfig {
+    projectId: string;
+    entry: {
+        worker: string;
+        container?: string;
+    };
+    environments: Record<EnvironmentName, EnvironmentConfig>;
+    bindings: Record<string, BindingDeclaration>;
+    workflows?: WorkflowsConfig;
+}
+export declare function defineConfig(config: VoyantConfig): VoyantConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -0,0 +1,7 @@
+// @voyant-travel/workflows/config
+//
+// Types and `defineConfig` helper for `voyant.config.ts`.
+// Contract defined in docs/sdk-surface.md §10 and docs/design.md §5.4.3.
+export function defineConfig(config) {
+    return config;
+}

package/dist/driver.d.ts

@@ -0,0 +1,237 @@
+import type { WorkflowManifest } from "./protocol/index.js";
+import type { ListRunsOptions, Run, RunDetail, RunSummary, TriggerOptions } from "./trigger.js";
+import type { EnvironmentName, WaitpointKind } from "./types.js";
+import type { WorkflowDefinition } from "./workflow.js";
+/**
+ * Read-only view of a service container. Step bodies resolve services via
+ * `ctx.services.resolve(...)`. The framework's `ModuleContainer`
+ * (in `@voyant-travel/core`) satisfies this shape structurally; we don't import
+ * it directly to keep `@voyant-travel/workflows` a leaf package.
+ */
+export interface ServiceResolver {
+    resolve<T>(name: string): T;
+    has(name: string): boolean;
+}
+/**
+ * Structural shape of an event envelope as ingested by a driver. Matches
+ * `EventEnvelope` from `@voyant-travel/core` (`name`, `data`, `metadata?`, `emittedAt`),
+ * declared structurally so the SDK package doesn't import core.
+ */
+export interface IngestEventEnvelope<TData = unknown> {
+    /** Event name in `<resource>.<pastTenseAction>` form. */
+    name: string;
+    /** Business payload. */
+    data: TData;
+    /** Optional metadata. `metadata.eventId` is the canonical idempotency seed
+     *  (a fresh ULID, stamped by the framework's EventBus forwarder). External
+     *  callers may supply their own. See architecture doc §15.2. */
+    metadata?: Record<string, unknown> & {
+        eventId?: string;
+    };
+    /** ISO timestamp string. */
+    emittedAt: string;
+}
+/**
+ * Minimal logger contract drivers can rely on. Matches the framework logger's
+ * call signature without taking a hard dependency on it.
+ */
+export type DriverLogger = (level: "debug" | "info" | "warn" | "error", msg: string, data?: object) => void;
+/**
+ * Deps the framework injects into a `DriverFactory` at boot. Driver factories
+ * close over their environment-specific options (DO bindings, DB pool, etc.)
+ * and read framework deps from this argument.
+ */
+export interface DriverFactoryDeps {
+    /** Read-only view of the framework's `ModuleContainer`. */
+    services: ServiceResolver;
+    /** Framework logger. */
+    logger: DriverLogger;
+    /** Injectable clock — defaults to `() => Date.now()`. */
+    now?: () => number;
+}
+/**
+ * Concrete driver factories return this. `createApp()` calls it once, after
+ * the container is built, to obtain the `WorkflowDriver`.
+ */
+export type DriverFactory = (deps: DriverFactoryDeps) => WorkflowDriver;
+/**
+ * Argument to `driver.ingestEvent(...)`. The framework's EventBus forwarder
+ * builds this from the core `EventEnvelope`; external HTTP callers (the
+ * optional ingest adapter, voyant-cloud) build it from a wire payload.
+ */
+export interface IngestEventArgs {
+    environment: EnvironmentName;
+    envelope: IngestEventEnvelope;
+    /** Optional caller-supplied idempotency override. When absent, the driver
+     *  derives a key per match from `metadata.eventId` (or a content hash
+     *  fallback). See architecture doc §15.2. */
+    idempotencyKey?: string;
+}
+/** Per-filter outcome from a single `ingestEvent` call. */
+export type IngestMatch = {
+    filterId: string;
+    targetWorkflowId: string;
+    runId: string;
+    idempotencyKey: string;
+    status: "queued";
+} | {
+    filterId: string;
+    status: "skipped";
+    reason: "where_eval_error" | "input_projection_error" | "input_schema_violation";
+    details?: string;
+} | {
+    filterId: string;
+    targetWorkflowId: string;
+    status: "error";
+    reason: string;
+};
+export type IngestEventResponse = {
+    ok: true;
+    eventId: string;
+    matches: IngestMatch[];
+} | {
+    ok: false;
+    reason: "manifest_not_registered" | "environment_mismatch" | "payload_too_large" | "trigger_failed_for_all_matches";
+    message?: string;
+};
+/**
+ * The mandatory driver contract. Every concrete driver — InMemory, Mode 2
+ * (Postgres), Mode 1 (CF edge) — implements all five methods. The compliance
+ * test suite (`driver-compliance.test.ts`) is the contract.
+ */
+export interface WorkflowDriver {
+    /**
+     * Idempotent. Same manifest body returns the same `versionId` across calls.
+     * Failures are NOT swallowed — `createApp()`'s bootstrap surfaces rejections
+     * (see architecture doc §21.22).
+     */
+    registerManifest(args: {
+        environment: EnvironmentName;
+        manifest: WorkflowManifest;
+    }): Promise<{
+        versionId: string;
+    }>;
+    /**
+     * Trigger a workflow run by id or definition handle. Honors
+     * `opts.idempotencyKey` for dedup (returns the existing run on conflict).
+     */
+    trigger<TIn, TOut>(workflow: WorkflowDefinition<TIn, TOut> | string, input: TIn, opts?: TriggerOptions): Promise<Run<TOut>>;
+    /**
+     * Ingest one event. Synchronously (from the caller's POV) loads the
+     * registered manifest, evaluates `where`, projects `input`, and triggers
+     * one run per match. See architecture doc §15.
+     */
+    ingestEvent(args: IngestEventArgs): Promise<IngestEventResponse>;
+    /**
+     * Read the registered manifest. Used at boot for version-mismatch detection
+     * and by the dashboard for filter inspection.
+     */
+    getManifest(args: {
+        environment: EnvironmentName;
+    }): Promise<WorkflowManifest | null>;
+    /**
+     * Optional. Drains in-flight steps, refuses new triggers, awaits time-wheel
+     * exit. Default `gracefulMs` is 30_000.
+     */
+    shutdown?(opts?: {
+        gracefulMs?: number;
+    }): Promise<void>;
+    /**
+     * Optional read-side surface. Drivers that can support listings, run detail,
+     * and journal streams declare this; consumers (the dashboard) duck-type on
+     * `driver.admin`. See architecture doc §6.2.
+     */
+    admin?: WorkflowAdmin | Partial<WorkflowAdmin>;
+}
+/**
+ * Read-side operations. Implemented natively by the Mode 2 driver against
+ * Postgres, partially by Mode 1 (single-run reads only — `listRuns` is not
+ * implemented in self-host Mode 1; voyant-cloud provides an index layer).
+ * See architecture doc §6.2 + §8.3.
+ */
+export interface WorkflowAdmin {
+    listRuns(opts?: ListRunsOptions): Promise<{
+        runs: RunSummary[];
+        nextCursor?: string;
+    }>;
+    getRun(runId: string): Promise<RunDetail | null>;
+    cancelRun(runId: string, opts?: {
+        reason?: string;
+        compensate?: boolean;
+    }): Promise<void>;
+    /**
+     * Subscribe to journal events for a run. The async-iterable shape lets
+     * dashboards stream live without polling.
+     */
+    streamRun(runId: string): AsyncIterable<AdminStreamEvent>;
+}
+/**
+ * The admin streaming surface re-uses the protocol's `StreamEvent` for
+ * step/waitpoint/log events; this type is its alias to keep the import
+ * surface narrow.
+ */
+export type AdminStreamEvent = {
+    kind: "run.snapshot";
+    at: number;
+    status: string;
+    metadata: Record<string, unknown>;
+} | {
+    kind: "step.started";
+    at: number;
+    stepId: string;
+    runtime: "edge" | "node";
+} | {
+    kind: "step.ok";
+    at: number;
+    stepId: string;
+    durationMs: number;
+} | {
+    kind: "step.err";
+    at: number;
+    stepId: string;
+    error: {
+        code: string;
+        message: string;
+    };
+} | {
+    kind: "waitpoint.registered";
+    at: number;
+    waitpointId: string;
+    waitpointKind: WaitpointKind;
+} | {
+    kind: "waitpoint.resolved";
+    at: number;
+    waitpointId: string;
+} | {
+    kind: "log";
+    at: number;
+    level: "info" | "warn" | "error";
+    message: string;
+} | {
+    kind: "run.finished";
+    at: number;
+    status: string;
+};
+/**
+ * Base class for typed driver errors. Concrete subclasses below; consumers
+ * `instanceof` to handle specific cases.
+ */
+export declare class WorkflowDriverError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class ManifestNotRegisteredError extends WorkflowDriverError {
+    constructor(environment: EnvironmentName);
+}
+export declare class EventTooLargeError extends WorkflowDriverError {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number, limit?: number);
+}
+export declare class EnvironmentMismatchError extends WorkflowDriverError {
+    constructor(eventEnv: EnvironmentName, manifestEnv: EnvironmentName);
+}
+//# sourceMappingURL=driver.d.ts.map