@voyantjs/hono 0.28.1 → 0.29.0

package/dist/app.d.ts

@@ -1,7 +1,35 @@
 import { Hono } from "hono";
 import type { VoyantAppConfig, VoyantBindings, VoyantVariables } from "./types.js";
+/**
+ * App handle returned alongside the Hono instance. Carries `ready()` for
+ * headless / sibling-process deployments that need to fire the lazy
+ * bootstrap before the first HTTP request — workflow runtimes (Mode 2's
+ * sibling-process pattern, tests) call this so the time wheel and
+ * manifest registration kick off without traffic.
+ *
+ * Returned via the augmented Hono instance: `app.ready` is attached
+ * directly so the existing call sites (which destructure / pass `app`
+ * around) keep working without a wrapper.
+ */
+export interface VoyantAppExtensions<TBindings = unknown> {
+    /**
+     * Resolves once the lazy bootstrap completes. Idempotent — multiple
+     * calls share the same promise. Use from tests + Mode 2 sibling
+     * processes where no request will arrive to trigger boot. See
+     * architecture doc §18 + §18.1.
+     *
+     * Accepts the runtime bindings that the bootstrap should run with. For
+     * binding-dependent configs (e.g. Mode 1 / Cloudflare, where the driver
+     * factory reads DO + KV bindings off `env`) callers MUST pass the real
+     * bindings; otherwise the memoized bootstrap promise locks in a driver
+     * built from `{}` and every later request reuses that broken instance.
+     * Mode 2 / InMemory drivers ignore bindings, so the no-arg form is safe
+     * there (defaults to `{}` for back-compat with tests).
+     */
+    ready(bindings?: TBindings): Promise<void>;
+}
 export declare function createApp<TBindings extends VoyantBindings>(config: VoyantAppConfig<TBindings>): Hono<{
     Bindings: TBindings;
     Variables: VoyantVariables;
-}>;
+}> & VoyantAppExtensions<TBindings>;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAS3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBlF,wBAAgB,SAAS,CAAC,SAAS,SAAS,cAAc,EACxD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,CAiJ3D"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAS3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBlF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,OAAO;IACtD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAED,wBAAgB,SAAS,CAAC,SAAS,SAAS,cAAc,EACxD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAuP5F"}

package/dist/app.js

@@ -1,4 +1,5 @@
-import { createContainer, createEventBus, createQueryRunner } from "@voyantjs/core";
+import { createContainer, createEventBus, createQueryRunner, } from "@voyantjs/core";
+import { buildManifest } from "@voyantjs/workflows/events";
 import { Hono } from "hono";
 import { requireAuth } from "./middleware/auth.js";
 import { cors } from "./middleware/cors.js";
@@ -40,11 +41,85 @@ export function createApp(config) {
     for (const sub of expanded?.subscribers ?? []) {
         eventBus.subscribe(sub.event, sub.handler);
     }
+    // ---- Workflow runtime wiring (synchronous setup; manifest registration
+    //      + EventBus forwarder run inside the lazy bootstrap below) ----
+    //
+    // We collect `workflows` + `eventFilters` from every module and plugin
+    // here so the failure mode for "duplicate workflow id across modules"
+    // surfaces at construction time (per architecture doc §18, the workflow
+    // runtime is fail-closed).
+    const collectedWorkflows = [];
+    const collectedFilters = [];
+    for (const mod of allModules) {
+        if (mod.module.workflows)
+            collectedWorkflows.push(...mod.module.workflows);
+        if (mod.module.eventFilters)
+            collectedFilters.push(...mod.module.eventFilters);
+    }
+    for (const plugin of config.plugins ?? []) {
+        if (plugin.workflows)
+            collectedWorkflows.push(...plugin.workflows);
+        if (plugin.eventFilters)
+            collectedFilters.push(...plugin.eventFilters);
+    }
+    // Validate duplicate workflow ids across modules + plugins. Same id from
+    // re-imports (HMR / shared bundles) is fine because identity is by id —
+    // we only flag genuinely-different definitions sharing an id.
+    if (config.workflows && collectedWorkflows.length > 0) {
+        const seen = new Map();
+        for (const wf of collectedWorkflows) {
+            const existing = seen.get(wf.id);
+            if (existing && existing !== wf) {
+                throw new Error(`[voyant] duplicate workflow id "${wf.id}" registered by multiple modules/plugins. ` +
+                    `Workflow ids must be unique across the app — use a module-scoped prefix ` +
+                    `(e.g. "${wf.id.includes(".") ? wf.id : `<module>.${wf.id}`}").`);
+            }
+            seen.set(wf.id, wf);
+        }
+    }
+    // Workflow driver construction is **deferred** to the lazy bootstrap
+    // path so CF-edge users (whose driver options come from `env.*`
+    // bindings only available at request time) can pass a function-of-
+    // bindings shape — `(env) => createCloudflareEdgeDriver({...})` —
+    // rather than constructing at module-load time. Mode 2 / InMemory
+    // users pass a direct factory; the framework adapts both shapes.
+    // See reviewer feedback P2.1 + architecture doc §6.3.
+    // biome-ignore lint/suspicious/noExplicitAny: WorkflowDriver shape varies across driver implementations
+    let workflowDriver;
     let bootstrapPromise = null;
     function ensureRuntimeBootstrapped(bindings) {
         if (!bootstrapPromise) {
             bootstrapPromise = (async () => {
                 const ctx = { bindings, container, eventBus };
+                // ---- Workflow runtime FIRST — fail-closed manifest registration
+                //      and EventBus forwarder must be in place before any module
+                //      bootstrap can emit. Otherwise a `module.bootstrap` that
+                //      emits an event during its own bootstrap would route through
+                //      a bus with no workflow forwarder yet, silently losing the
+                //      event. Per architecture doc §21.22 + reviewer feedback P2.3.
+                if (config.workflows) {
+                    // `driver` is always a function-of-bindings (per
+                    // VoyantWorkflowsConfig — see types.ts + reviewer feedback P2.1).
+                    // Mode 2 / InMemory users wrap with `() => createXxxDriver({...})`.
+                    // CF-edge users use `(env) => createCloudflareEdgeDriver({ env.* })`.
+                    // We invoke with bindings, then the resulting DriverFactory
+                    // with framework deps.
+                    const factoryDeps = {
+                        services: containerToServiceResolver(container),
+                        logger: makeFrameworkLogger(config.logger),
+                    };
+                    const factory = config.workflows.driver(bindings);
+                    workflowDriver = factory(factoryDeps);
+                    await wireWorkflowRuntime({
+                        modules: allModules.map((m) => m.module),
+                        collectedWorkflows,
+                        collectedFilters,
+                        driver: workflowDriver,
+                        environment: config.workflows.environment ?? "development",
+                        projectId: config.workflows.projectId ?? "default",
+                        eventBus,
+                    });
+                }
                 // Run each bootstrap in isolation — a single failing plugin/module/extension
                 // must not poison the cached promise and kill the whole app's request pipeline.
                 const runIsolated = async (label, fn) => {
@@ -80,7 +155,18 @@ export function createApp(config) {
         if (query) {
             c.set("query", query);
         }
+        // Bootstrap (fires once, idempotent) — resolves the workflow driver
+        // with c.env-supplied bindings on the first request, so deferred
+        // driver construction sees real runtime bindings (reviewer P2.1).
         await ensureRuntimeBootstrapped(c.env);
+        if (workflowDriver) {
+            // Surfaced on `c.var.workflowDriver` so HTTP route handlers can
+            // call `driver.trigger(...)` directly without re-resolving from
+            // the container. Also used by the optional HTTP ingest adapter
+            // (`mountHttpIngestAdapter` from `@voyantjs/workflows/http-ingest`).
+            ;
+            c.set("workflowDriver", workflowDriver);
+        }
         return next();
     });
     // Request ID header
@@ -134,5 +220,137 @@ export function createApp(config) {
     if (config.additionalRoutes) {
         config.additionalRoutes(app);
     }
-    return app;
+    // Attach `ready()` directly to the Hono instance. Fires the lazy
+    // bootstrap with the supplied bindings (or `{}` for back-compat with
+    // Mode 2 / InMemory drivers that ignore them). Production code never
+    // calls `ready()` — the first request triggers the same boot via
+    // `ensureRuntimeBootstrapped(c.env)`. Tests + Mode 2 sibling processes
+    // use this so the time wheel + manifest registration happen without
+    // traffic; CF-edge users that want eager boot must pass the real `env`
+    // (otherwise the memoized bootstrap promise locks in a driver built
+    // from `{}` and every later request reuses that broken instance).
+    const augmented = app;
+    augmented.ready = (bindings) => ensureRuntimeBootstrapped(bindings ?? {});
+    return augmented;
+}
+/**
+ * Build the manifest, register it with the driver, and install a single
+ * EventBus subscriber per unique eventType seen across the manifest's
+ * filters — that subscriber forwards into `driver.ingestEvent(...)`.
+ *
+ * The forwarder stamps `metadata.eventId` with a fresh content-derived
+ * id when missing, so the framework's idempotency derivation
+ * (`${filterId}:${eventId}`) gives stable run-dedup across retries.
+ *
+ * Failure modes are fail-closed: a manifest registration that throws
+ * rejects the bootstrap promise, and the next request sees a 503 with
+ * the registration error in the body.
+ */
+async function wireWorkflowRuntime(args) {
+    // The descriptors collected from modules + plugins use core's structural
+    // types (`{ id, eventType }` only — see `EventFilterDescriptor` in core);
+    // the manifest builder needs the runtime shape with `.manifest` populated.
+    // Validate before casting so a contract-violating plugin fails loudly here
+    // instead of crashing on `entry.manifest.id` deep inside the sort.
+    const filterEntries = [];
+    for (const entry of args.collectedFilters) {
+        const candidate = entry;
+        if (!candidate.manifest || typeof candidate.manifest.id !== "string") {
+            throw new Error(`[voyant] event filter "${entry.id}" (event "${entry.eventType}") is missing the runtime ` +
+                `\`manifest\` field. Filters must be produced via \`trigger.on(eventName, { ... })\` from ` +
+                `@voyantjs/workflows — the public EventFilterDescriptor is the structural minimum, but ` +
+                `createApp() needs the manifest payload to register with the driver.`);
+        }
+        filterEntries.push(candidate);
+    }
+    const manifest = await buildManifest({
+        projectId: args.projectId,
+        environment: args.environment,
+        workflows: args.collectedWorkflows.map((w) => ({ id: w.id })),
+        eventFilters: filterEntries,
+    });
+    await args.driver.registerManifest({
+        environment: args.environment,
+        manifest,
+    });
+    // Install one EventBus subscriber per unique eventType. Each subscriber
+    // forwards the envelope through `driver.ingestEvent(...)`, which
+    // routes through the same predicate/mapper machinery the HTTP
+    // ingest path uses (see architecture doc §15).
+    const eventTypes = new Set(filterEntries.map((f) => f.eventType));
+    for (const eventType of eventTypes) {
+        args.eventBus.subscribe(eventType, async (envelope) => {
+            const stamped = ensureMetadataEventId(envelope);
+            try {
+                await args.driver.ingestEvent({
+                    environment: args.environment,
+                    envelope: stamped,
+                });
+            }
+            catch (err) {
+                // Subscribers are observers per the EventBus contract — a misbehaving
+                // driver / network glitch must not break the emitter. The driver's
+                // own error reporting (logger calls + counter increments) surfaces
+                // the failure for ops; we swallow here to preserve the bus contract.
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[voyant] workflow forwarder for "${eventType}" failed: ${message}`);
+            }
+        });
+    }
+}
+/**
+ * Adapt the framework's `ModuleContainer` (which has `register`) to a
+ * read-only `ServiceResolver` view (`resolve` + `has` only). This is
+ * what driver factories receive in their `services` dep.
+ */
+function containerToServiceResolver(container) {
+    return {
+        resolve(name) {
+            return container.resolve(name);
+        },
+        has(name) {
+            return container.has(name);
+        },
+    };
+}
+/**
+ * Adapt the framework's optional `LoggerProvider` to the structural
+ * `DriverLogger` shape `(level, msg, data?) => void`. When no logger
+ * is configured, the adapter routes through `console`.
+ */
+function makeFrameworkLogger(loggerProvider) {
+    void loggerProvider;
+    return (level, msg, data) => {
+        const fn = level === "error"
+            ? console.error
+            : level === "warn"
+                ? console.warn
+                : level === "debug"
+                    ? console.debug
+                    : console.log;
+        if (data !== undefined)
+            fn(`[voyant] ${msg}`, data);
+        else
+            fn(`[voyant] ${msg}`);
+    };
+}
+function ensureMetadataEventId(envelope) {
+    const metadata = envelope.metadata;
+    if (metadata !== undefined &&
+        metadata !== null &&
+        typeof metadata === "object" &&
+        typeof metadata.eventId === "string" &&
+        (metadata.eventId.length ?? 0) > 0) {
+        return envelope;
+    }
+    const eventId = `evt_${Date.now().toString(36)}_${Math.floor(Math.random() * 1_000_000)
+        .toString(36)
+        .padStart(4, "0")}`;
+    return {
+        ...envelope,
+        metadata: {
+            ...(metadata ?? {}),
+            eventId,
+        },
+    };
 }

package/dist/middleware/auth.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import type { DbFactory, VoyantAuthIntegration, VoyantBindings, VoyantVariables } from "../types.js";
+import { type DbFactory, type VoyantAuthIntegration, type VoyantBindings, type VoyantVariables } from "../types.js";
 export declare function requireAuth<TBindings extends VoyantBindings>(dbFactory: DbFactory<TBindings>, opts?: {
     publicPaths?: string[];
     auth?: VoyantAuthIntegration<TBindings>;

package/dist/middleware/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAI7C,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAsCpG,wBAAgB,WAAW,CAAC,SAAS,SAAS,cAAc,EAC1D,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,IAAI,CAAC,EAAE;IACL,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,IAAI,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAA;CACxC,GACA,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CA4ID"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAI7C,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAA;AAsCpB,wBAAgB,WAAW,CAAC,SAAS,SAAS,cAAc,EAC1D,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,IAAI,CAAC,EAAE;IACL,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,IAAI,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAA;CACxC,GACA,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CAqJD"}

package/dist/middleware/auth.js

@@ -2,6 +2,7 @@ import { apikeyTable } from "@voyantjs/db/schema/iam";
 import { and, eq } from "drizzle-orm";
 import { sha256Base64Url } from "../auth/crypto.js";
 import { extractBearerToken, verifySession } from "../auth/session-jwt.js";
+import { resolveDbFactoryResult, } from "../types.js";
 function permissionsToScopes(permissions) {
     if (!permissions)
         return [];
@@ -72,8 +73,8 @@ export function requireAuth(dbFactory, opts) {
         }
         // Strategy 2: Core-owned API key support (voy_ prefixed)
         if (token?.startsWith(API_KEY_PREFIX)) {
+            const { db, dispose } = resolveDbFactoryResult(dbFactory(c.env));
             try {
-                const db = dbFactory(c.env);
                 const keyHash = await sha256Base64Url(token);
                 const [row] = await db
                     .select()
@@ -128,18 +129,31 @@ export function requireAuth(dbFactory, opts) {
             catch {
                 // fall through to next strategy
             }
+            finally {
+                // Schedule pool teardown AFTER the queries above settle. waitUntil
+                // keeps the worker alive for the close handshake.
+                if (dispose)
+                    c.executionCtx.waitUntil?.(dispose());
+            }
         }
         // Strategy 3: App-provided auth resolution (cookies, provider tokens, etc.)
         if (opts?.auth?.resolve) {
-            const resolved = await opts.auth.resolve({
-                request: c.req.raw,
-                env: c.env,
-                db: dbFactory(c.env),
-                ctx: c.executionCtx,
-            });
-            if (resolved?.userId) {
-                applyAuthContext(c, resolved);
-                return next();
+            const { db: resolveDb, dispose: resolveDispose } = resolveDbFactoryResult(dbFactory(c.env));
+            try {
+                const resolved = await opts.auth.resolve({
+                    request: c.req.raw,
+                    env: c.env,
+                    db: resolveDb,
+                    ctx: c.executionCtx,
+                });
+                if (resolved?.userId) {
+                    applyAuthContext(c, resolved);
+                    return next();
+                }
+            }
+            finally {
+                if (resolveDispose)
+                    c.executionCtx.waitUntil?.(resolveDispose());
             }
         }
         // Strategy 4: Generic session-claims bearer token support

package/dist/middleware/db.d.ts

@@ -1,5 +1,19 @@
 import type { MiddlewareHandler } from "hono";
-import type { DbFactory, VoyantBindings, VoyantDb } from "../types.js";
+import { type DbFactory, type VoyantBindings, type VoyantDb } from "../types.js";
+/**
+ * Resolves the per-request db client and stores it on Hono context.
+ *
+ * If the factory returns a {@link DisposableDb} (e.g. a
+ * `dbFromEnvForApp` that owns a per-request Neon WebSocket Pool), the
+ * middleware schedules `dispose()` via `c.executionCtx.waitUntil` so
+ * the Pool closes cleanly after the response is sent. Without the
+ * scheduled dispose every request would leak its Pool until isolate
+ * teardown, which at scale exhausts Neon's connection budget.
+ *
+ * Factories that return a plain {@link VoyantDb} (e.g. a long-lived
+ * postgres-js client cached at the module level) are wired up as
+ * before with no cleanup hook.
+ */
 export declare function db<TBindings extends VoyantBindings>(factory: DbFactory<TBindings>): MiddlewareHandler<{
     Bindings: TBindings;
     Variables: {

package/dist/middleware/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/middleware/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtE,wBAAgB,EAAE,CAAC,SAAS,SAAS,cAAc,EACjD,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,GAC5B,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE;QAAE,EAAE,EAAE,QAAQ,CAAA;KAAE,CAAA;CAC5B,CAAC,CAKD"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/middleware/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,EAAE,KAAK,SAAS,EAAkB,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAYhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,EAAE,CAAC,SAAS,SAAS,cAAc,EACjD,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,GAC5B,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE;QAAE,EAAE,EAAE,QAAQ,CAAA;KAAE,CAAA;CAC5B,CAAC,CAuBD"}

package/dist/middleware/db.js

@@ -1,6 +1,41 @@
+import { isDisposableDb } from "../types.js";
+/**
+ * Resolves the per-request db client and stores it on Hono context.
+ *
+ * If the factory returns a {@link DisposableDb} (e.g. a
+ * `dbFromEnvForApp` that owns a per-request Neon WebSocket Pool), the
+ * middleware schedules `dispose()` via `c.executionCtx.waitUntil` so
+ * the Pool closes cleanly after the response is sent. Without the
+ * scheduled dispose every request would leak its Pool until isolate
+ * teardown, which at scale exhausts Neon's connection budget.
+ *
+ * Factories that return a plain {@link VoyantDb} (e.g. a long-lived
+ * postgres-js client cached at the module level) are wired up as
+ * before with no cleanup hook.
+ */
 export function db(factory) {
     return async (c, next) => {
-        c.set("db", factory(c.env));
+        const result = factory(c.env);
+        if (isDisposableDb(result)) {
+            c.set("db", result.db);
+            try {
+                await next();
+            }
+            finally {
+                // `executionCtx` is undefined in unit-test contexts where Hono
+                // is invoked directly without a Workers runtime — fall back to
+                // an inline await so cleanup still runs.
+                const ctx = c.executionCtx;
+                if (ctx && typeof ctx.waitUntil === "function") {
+                    ctx.waitUntil(result.dispose());
+                }
+                else {
+                    await result.dispose();
+                }
+            }
+            return;
+        }
+        c.set("db", result);
         await next();
     };
 }

package/dist/middleware/error-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/middleware/error-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAYtD,eAAO,MAAM,SAAS,EAAE,iBAKvB,CAAA;AAID,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CA+CjE;AAED,eAAO,MAAM,aAAa,EAAE,iBAM3B,CAAA"}
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/middleware/error-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAYtD,eAAO,MAAM,SAAS,EAAE,iBAKvB,CAAA;AAID,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CAiDjE;AAED,eAAO,MAAM,aAAa,EAAE,iBAM3B,CAAA"}

package/dist/middleware/error-boundary.js

@@ -42,6 +42,8 @@ export function handleApiError(err, c) {
             method: c.req.method,
             headers,
             err: err instanceof Error ? err.message : String(err),
+            cause: err instanceof Error && err.cause ? String(err.cause) : undefined,
+            stack: err instanceof Error ? err.stack : undefined,
         });
     }
     catch {

package/dist/middleware/idempotency-key.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import type { DbFactory, VoyantBindings, VoyantVariables } from "../types.js";
+import { type DbFactory, type VoyantBindings, type VoyantVariables } from "../types.js";
 /**
  * Twenty-four hours, in milliseconds. Default TTL for stored idempotency
  * keys. Tunable per middleware instance.
@@ -63,6 +63,10 @@ export declare function idempotencyKey<TBindings extends VoyantBindings = Voyant
 }>;
 /**
  * Sweep expired idempotency rows. Call from a daily cron.
+ *
+ * If `dbFactory` returns a `DisposableDb` (e.g. a per-call Neon
+ * WebSocket Pool), the sweep awaits `dispose()` before returning so
+ * the connection closes cleanly inside the cron handler.
  */
 export declare function purgeExpiredIdempotencyKeys<TBindings extends VoyantBindings>(dbFactory: DbFactory<TBindings>, env: TBindings): Promise<{
     removed: number;

package/dist/middleware/idempotency-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency-key.d.ts","sourceRoot":"","sources":["../../src/middleware/idempotency-key.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAsB,CAAA;AAmB7D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAClE;AAED,UAAU,sBAAsB;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAmB,SAAQ,sBAAsB;KAAG;CAC/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,SAAS,SAAS,cAAc,GAAG,cAAc,EAC9E,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CAkID;AAiBD;;GAEG;AACH,wBAAsB,2BAA2B,CAAC,SAAS,SAAS,cAAc,EAChF,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,GAAG,EAAE,SAAS,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAO9B"}
+{"version":3,"file":"idempotency-key.d.ts","sourceRoot":"","sources":["../../src/middleware/idempotency-key.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAA;AAEpB;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAsB,CAAA;AAmB7D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAClE;AAED,UAAU,sBAAsB;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAmB,SAAQ,sBAAsB;KAAG;CAC/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,SAAS,SAAS,cAAc,GAAG,cAAc,EAC9E,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CAoID;AAiBD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAAC,SAAS,SAAS,cAAc,EAChF,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,GAAG,EAAE,SAAS,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAa9B"}

package/dist/middleware/idempotency-key.js

@@ -1,5 +1,6 @@
 import { infraIdempotencyKeysTable } from "@voyantjs/db/schema/infra";
 import { and, eq, lt } from "drizzle-orm";
+import { isDisposableDb, } from "../types.js";
 /**
  * Twenty-four hours, in milliseconds. Default TTL for stored idempotency
  * keys. Tunable per middleware instance.
@@ -58,6 +59,8 @@ export function idempotencyKey(options = {}) {
         const scope = options.scope ?? `${c.req.method} ${new URL(c.req.url).pathname}`;
         const rawBody = await c.req.text();
         const bodyHash = await sha256Hex(rawBody);
+        // The `db` middleware always unwraps a `DisposableDb` to a plain
+        // `VoyantDb` before storing on context, so this cast is safe.
         const db = c.get("db");
         if (!db) {
             throw new Error("idempotencyKey middleware requires `db` on the request context. Mount `db()` (or `createApp`) before this middleware.");
@@ -168,12 +171,24 @@ function pickStringField(body, keys) {
 }
 /**
  * Sweep expired idempotency rows. Call from a daily cron.
+ *
+ * If `dbFactory` returns a `DisposableDb` (e.g. a per-call Neon
+ * WebSocket Pool), the sweep awaits `dispose()` before returning so
+ * the connection closes cleanly inside the cron handler.
  */
 export async function purgeExpiredIdempotencyKeys(dbFactory, env) {
-    const db = dbFactory(env);
-    const result = await db
-        .delete(infraIdempotencyKeysTable)
-        .where(lt(infraIdempotencyKeysTable.expiresAt, new Date()))
-        .returning();
-    return { removed: result.length };
+    const result = dbFactory(env);
+    const db = isDisposableDb(result) ? result.db : result;
+    const dispose = isDisposableDb(result) ? result.dispose : undefined;
+    try {
+        const rows = await db
+            .delete(infraIdempotencyKeysTable)
+            .where(lt(infraIdempotencyKeysTable.expiresAt, new Date()))
+            .returning();
+        return { removed: rows.length };
+    }
+    finally {
+        if (dispose)
+            await dispose();
+    }
 }

package/dist/middleware/require-permission.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import type { DbFactory, VoyantAuthIntegration, VoyantBindings, VoyantVariables } from "../types.js";
+import { type DbFactory, type VoyantAuthIntegration, type VoyantBindings, type VoyantVariables } from "../types.js";
 export declare function requirePermission<TBindings extends VoyantBindings>(dbFactory: DbFactory<TBindings>, resource: string, action: string, opts?: {
     auth?: VoyantAuthIntegration<TBindings>;
 }): MiddlewareHandler<{

package/dist/middleware/require-permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"require-permission.d.ts","sourceRoot":"","sources":["../../src/middleware/require-permission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAG7C,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAepG,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,cAAc,EAChE,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAA;CACxC,GACA,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CAkDD"}
+{"version":3,"file":"require-permission.d.ts","sourceRoot":"","sources":["../../src/middleware/require-permission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAG7C,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAA;AAqBpB,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,cAAc,EAChE,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAA;CACxC,GACA,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAC,CAiED"}

package/dist/middleware/require-permission.js

@@ -1,4 +1,5 @@
 import { requireUserId } from "../auth/require-user.js";
+import { isDisposableDb, } from "../types.js";
 import { ForbiddenApiError, UnauthorizedApiError } from "../validation.js";
 function hasScope(scopes, permission) {
     if (!scopes || scopes.length === 0)
@@ -30,26 +31,42 @@ export function requirePermission(dbFactory, resource, action, opts) {
         if (!opts?.auth?.hasPermission) {
             return c.json({ error: "No auth permission checker configured" }, 500);
         }
-        const allowed = await opts.auth.hasPermission({
-            request: c.req.raw,
-            env: c.env,
-            db: dbFactory(c.env),
-            ctx: c.executionCtx,
-            auth: {
-                userId,
-                actor,
-                sessionId: c.get("sessionId"),
-                organizationId: c.get("organizationId"),
-                callerType: c.get("callerType"),
-                scopes,
-                isInternalRequest: c.get("isInternalRequest"),
-                apiKeyId: c.get("apiKeyId"),
-            },
-            permission,
-        });
-        if (!allowed) {
-            throw new ForbiddenApiError();
+        const factoryResult = dbFactory(c.env);
+        const db = isDisposableDb(factoryResult) ? factoryResult.db : factoryResult;
+        const dispose = isDisposableDb(factoryResult) ? factoryResult.dispose : undefined;
+        try {
+            const allowed = await opts.auth.hasPermission({
+                request: c.req.raw,
+                env: c.env,
+                db,
+                ctx: c.executionCtx,
+                auth: {
+                    userId,
+                    actor,
+                    sessionId: c.get("sessionId"),
+                    organizationId: c.get("organizationId"),
+                    callerType: c.get("callerType"),
+                    scopes,
+                    isInternalRequest: c.get("isInternalRequest"),
+                    apiKeyId: c.get("apiKeyId"),
+                },
+                permission,
+            });
+            if (!allowed) {
+                throw new ForbiddenApiError();
+            }
+            return next();
+        }
+        finally {
+            if (dispose) {
+                const ctx = c.executionCtx;
+                if (ctx && typeof ctx.waitUntil === "function") {
+                    ctx.waitUntil(dispose());
+                }
+                else {
+                    await dispose();
+                }
+            }
         }
-        return next();
     };
 }

package/dist/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { BootstrapHandler, LinkDefinition, Subscriber } from "@voyantjs/core";
+import type { BootstrapHandler, EventFilterDescriptor, LinkDefinition, Subscriber, WorkflowDescriptor } from "@voyantjs/core";
 import type { HonoExtension, HonoModule } from "./module.js";
 /**
  * Hono-flavoured bundle contribution surface.
@@ -27,6 +27,17 @@ export interface HonoBundle {
     subscribers?: Subscriber[];
     /** Link definitions contributed by the plugin. */
     links?: LinkDefinition[];
+    /**
+     * Workflows contributed by the plugin. Mirrors the `Plugin.workflows`
+     * field in `@voyantjs/core` — collected at `createApp()` boot and
+     * registered with the configured workflow driver.
+     */
+    workflows?: readonly WorkflowDescriptor[];
+    /**
+     * Event filters contributed by the plugin. Mirrors
+     * `Plugin.eventFilters` in `@voyantjs/core`.
+     */
+    eventFilters?: readonly EventFilterDescriptor[];
 }
 /** @deprecated Prefer {@link HonoBundle}. */
 export type HonoPlugin = HonoBundle;

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,gEAAgE;IAChE,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAC5B,wEAAwE;IACxE,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,kDAAkD;IAClD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;CACzB;AAED,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEnE;AAED,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,yBAAmB,CAAA;AAEhD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,UAAU,EAAE,aAAa,EAAE,CAAA;IAC3B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,KAAK,EAAE,cAAc,EAAE,CAAA;CACxB;AAED,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,mBAAmB,CAoBzF;AAED,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,0BAAoB,CAAA"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,kBAAkB,EACnB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,gEAAgE;IAChE,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAC5B,wEAAwE;IACxE,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,kDAAkD;IAClD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAA;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAChD;AAED,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEnE;AAED,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,yBAAmB,CAAA;AAEhD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,UAAU,EAAE,aAAa,EAAE,CAAA;IAC3B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,KAAK,EAAE,cAAc,EAAE,CAAA;CACxB;AAED,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,mBAAmB,CAoBzF;AAED,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,0BAAoB,CAAA"}

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { Actor, VoyantVariables as CoreVoyantVariables, EventBus, LinkService, ModuleContainer, QueryGraphContext, QueryRunner, VoyantAuthContext, VoyantPermission } from "@voyantjs/core";
 import type { KVStore } from "@voyantjs/utils/cache";
 import type { NeonHttpDatabase } from "drizzle-orm/neon-http";
+import type { NeonDatabase as NeonWsDatabase } from "drizzle-orm/neon-serverless";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Hono } from "hono";
 import type { HonoExtension, HonoModule } from "./module.js";
@@ -21,7 +22,7 @@ export interface VoyantBindings {
     RATE_LIMIT?: KVStore;
     CACHE?: KVStore;
 }
-export type VoyantDb = PostgresJsDatabase | NeonHttpDatabase;
+export type VoyantDb = PostgresJsDatabase | NeonHttpDatabase | NeonWsDatabase;
 export type VoyantQueryRuntime = QueryRunner;
 export type VoyantVariables = CoreVoyantVariables & {
     db: VoyantDb;
@@ -33,7 +34,30 @@ export type VoyantVariables = CoreVoyantVariables & {
     /** Shared cross-module query runtime, when the app wires one in. */
     query?: VoyantQueryRuntime;
 };
-export type DbFactory<TBindings extends VoyantBindings = VoyantBindings> = (env: TBindings) => VoyantDb;
+/**
+ * Per-request handle returned by a {@link DbFactory} that owns its own
+ * Pool / connection: a drizzle client plus a `dispose()` the db
+ * middleware schedules via `c.executionCtx.waitUntil` after the
+ * response is sent. Used by templates that build a Neon WebSocket
+ * Pool per request (see e.g. `dbFromEnvForApp` in template
+ * `src/api/lib/db.ts`) — without `dispose()`, the Pool stays open
+ * until the Workers isolate is reclaimed.
+ */
+export interface DisposableDb {
+    db: VoyantDb;
+    dispose: () => Promise<void>;
+}
+export type DbFactory<TBindings extends VoyantBindings = VoyantBindings> = (env: TBindings) => VoyantDb | DisposableDb;
+export declare function isDisposableDb(value: VoyantDb | DisposableDb): value is DisposableDb;
+/**
+ * Normalize a {@link DbFactory} return value to `{ db, dispose? }` so
+ * call sites don't repeat the `isDisposableDb` shape check. `dispose`
+ * is `undefined` for plain `VoyantDb` factories.
+ */
+export declare function resolveDbFactoryResult(value: VoyantDb | DisposableDb): {
+    db: VoyantDb;
+    dispose?: () => Promise<void>;
+};
 /**
  * The shape returned by a custom `auth.resolve` integration. Both `userId`
  * and `actor` are required: `requireActor` is fail-closed, so a resolver
@@ -90,6 +114,76 @@ export interface VoyantAppConfig<TBindings extends VoyantBindings = VoyantBindin
     auth?: VoyantAuthIntegration<TBindings>;
     publicPaths?: string[];
     logger?: LoggerProvider;
+    /**
+     * Workflow runtime configuration. When set, `createApp()` collects
+     * `module.workflows` + `module.eventFilters` (plus the same fields
+     * from plugins), invokes `workflows.driver` with framework deps, and
+     * — inside the lazy bootstrap path — registers the manifest with the
+     * driver and installs an EventBus forwarder that routes emitted
+     * events to `driver.ingestEvent(...)`.
+     *
+     * See `docs/architecture/workflows-runtime-architecture.md` §6, §18.
+     */
+    workflows?: VoyantWorkflowsConfig;
     additionalRoutes?: (app: Hono<any>) => void;
 }
+/**
+ * Workflow runtime configuration block. The driver is resolved at boot
+ * time (inside the lazy bootstrap path), after framework deps and —
+ * crucially — after runtime bindings are available.
+ *
+ * `driver` is **always** a function-of-bindings: `(env) => DriverFactory`.
+ * This unambiguous shape works for all deployment modes:
+ *
+ * **Mode 2 / InMemory** — wrap your direct factory:
+ *
+ *     workflows: {
+ *       driver: () => createNodeStandaloneDriver({ db }),
+ *     }
+ *
+ * **Mode 1 (CF edge)** — pull options off `env`:
+ *
+ *     workflows: {
+ *       driver: (env) => createCloudflareEdgeDriver({
+ *         orchestratorNamespace: env.WORKFLOW_RUN_DO,
+ *         manifestKv: env.WORKFLOW_MANIFESTS,
+ *         tenantScript: "tenant-bundle",
+ *       }),
+ *     }
+ *
+ * The single shape avoids ambiguous "is this a factory or a
+ * factory-of-factories?" heuristics. See architecture doc §6.3 +
+ * reviewer feedback P2.1.
+ */
+export interface VoyantWorkflowsConfig<TBindings = unknown> {
+    /**
+     * Function-of-bindings that returns a `DriverFactory`. Resolved
+     * lazily with `c.env` once bindings are available, then invoked
+     * with `{ services, logger }` to produce the driver.
+     */
+    driver: (bindings: TBindings) => WorkflowDriverFactoryShape;
+    /**
+     * Environment the manifest registers under. Defaults to `"development"`.
+     * Workflow filters are environment-scoped (production manifests don't
+     * see preview events and vice versa) per architecture doc §21.10.
+     */
+    environment?: "production" | "preview" | "development";
+    /**
+     * Project / tenant identifier baked into the manifest. Single-tenant
+     * runtimes leave this unset (defaults to `"default"`). Multi-tenant
+     * deployments override per-app via voyant-cloud's wrapper layer.
+     */
+    projectId?: string;
+}
+/**
+ * Structural shape of a `DriverFactory` from `@voyantjs/workflows/driver`.
+ * The SDK package's concrete `DriverFactory` satisfies this via TS
+ * structural compat (architecture doc §21.19).
+ */
+type WorkflowDriverFactoryShape = (deps: {
+    services: any;
+    logger: any;
+    now?: () => number;
+}) => any;
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -1 +1,12 @@
-export {};
+export function isDisposableDb(value) {
+    return (typeof value.dispose === "function" &&
+        value.db !== undefined);
+}
+/**
+ * Normalize a {@link DbFactory} return value to `{ db, dispose? }` so
+ * call sites don't repeat the `isDisposableDb` shape check. `dispose`
+ * is `undefined` for plain `VoyantDb` factories.
+ */
+export function resolveDbFactoryResult(value) {
+    return isDisposableDb(value) ? value : { db: value };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/hono",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -94,16 +94,18 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.28.1",
-    "@voyantjs/db": "0.28.1",
-    "@voyantjs/types": "0.28.1",
-    "@voyantjs/utils": "0.28.1"
+    "@voyantjs/db": "0.29.0",
+    "@voyantjs/core": "0.29.0",
+    "@voyantjs/types": "0.29.0",
+    "@voyantjs/utils": "0.29.0",
+    "@voyantjs/workflows": "0.29.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260426.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
-    "@voyantjs/voyant-typescript-config": "0.1.0"
+    "@voyantjs/voyant-typescript-config": "0.1.0",
+    "@voyantjs/workflows-orchestrator": "0.29.0"
   },
   "files": [
     "dist"