lopata 0.18.3 → 0.19.0

package/dist/types/bindings/websocket-pair.d.ts

@@ -5,14 +5,18 @@
  * Messages sent on one side appear on the other.
  * Events are buffered until accept() is called.
  */
-type WSEventType = 'message' | 'close' | 'error' | 'open';
-interface WSEvent {
+export type WSEventType = 'message' | 'close' | 'error' | 'open';
+export interface WSEvent {
     type: WSEventType;
     data?: string | ArrayBuffer;
     code?: number;
     reason?: string;
     wasClean?: boolean;
 }
+/** Response with optional CF `webSocket` property — used by upgrade flows. */
+export type ResponseWithWebSocket = Response & {
+    webSocket?: CFWebSocket;
+};
 /**
  * A single side of a WebSocketPair. Implements the CF WebSocket interface
  * with accept() gating — events are queued until accept() is called.
@@ -48,6 +52,12 @@ export declare class CFWebSocket extends EventTarget {
     accept(): void;
     send(message: string | ArrayBuffer | ArrayBufferView): void;
     close(code?: number, reason?: string): void;
+    /**
+     * Deliver `evt` to local listeners if the peer is already `accept()`ed;
+     * otherwise queue it for replay. Centralises the "dispatch or queue" branch
+     * that every bridge implementation otherwise inlines.
+     */
+    dispatchOrQueue(evt: WSEvent): void;
     /** @internal */
     _dispatchWSEvent(evt: WSEvent): void;
 }
@@ -63,4 +73,3 @@ export declare class WebSocketPair {
     readonly 1: CFWebSocket;
     constructor();
 }
-export {};

package/dist/types/bindings/workflow.d.ts

@@ -1,5 +1,6 @@
 import type { Database } from 'bun:sqlite';
 import type { Clock } from '../testing/clock';
+import type { WorkflowControlOp, WorkflowControlResult } from '../worker-thread/protocol';
 export interface WorkflowLimits {
     maxConcurrentInstances?: number;
     maxRetentionMs?: number;
@@ -53,6 +54,12 @@ export declare function onEventWaitRegistered(instanceId: string, eventType: str
 /** Register a callback for when the instance status changes. Returns an unsubscribe function. */
 export declare function onStatusChange(instanceId: string, cb: (status: string) => void): () => void;
 export declare function parseDuration(duration: string | number): number;
+/**
+ * Wire a workflow class from the user module onto a `SqliteWorkflowBinding`.
+ * Both the in-process `wireClassRefs` and the worker-thread entry use this
+ * — keeps the lookup-throw-setClass-resumeInterrupted contract in one place.
+ */
+export declare function wireWorkflowClass(binding: SqliteWorkflowBinding, className: string, workerModule: Record<string, unknown>, env: Record<string, unknown>): void;
 export declare class WorkflowEntrypointBase {
     ctx: {
         env: unknown;
@@ -97,6 +104,13 @@ export declare class SqliteWorkflowBinding {
     private counter;
     private limits;
     private clock;
+    /**
+     * Thread-mode router for dashboard control ops. The real state machine lives
+     * in the worker thread, so when this is set `executeControl` forwards there
+     * instead of running against this (hollow) main-side binding. `null`/unset =
+     * in-process: run locally. Installed by `GenerationManager` on each reload.
+     */
+    private _threadRouter?;
     constructor(db: Database, workflowName: string, className: string, limits?: WorkflowLimits, clock?: Clock);
     _setClass(cls: new (ctx: unknown, env: unknown) => WorkflowEntrypointBase, env: unknown): void;
     _getClass(): (new (ctx: unknown, env: unknown) => WorkflowEntrypointBase) | undefined;
@@ -126,6 +140,21 @@ export declare class SqliteWorkflowBinding {
         params?: unknown;
     }[]): Promise<SqliteWorkflowInstance[]>;
     get(id: string): Promise<SqliteWorkflowInstance>;
+    /**
+     * Install the thread-mode router (see {@link _threadRouter}). Called by
+     * `GenerationManager` on each reload so the dashboard's control ops reach the
+     * live worker-side binding. Mirrors the DO namespace's `_setExternalClass`.
+     */
+    _setThreadRouter(router: (op: WorkflowControlOp) => Promise<WorkflowControlResult>): void;
+    /**
+     * Execute a dashboard control operation. In thread mode the real state
+     * machine (abort controllers, event waiters, sleep resolvers, the wired
+     * class) lives in the worker, so when a thread router is installed this
+     * forwards there; otherwise (in-process / worker-side binding) it runs
+     * locally. Mutating ops resolve to `{ kind: 'ok' }`; `create` reports the new
+     * id; the introspection reads report their value.
+     */
+    executeControl(op: WorkflowControlOp): Promise<WorkflowControlResult>;
     /** Resume any workflow instances that were running/waiting when the process last exited. */
     resumeInterrupted(): void;
     /** Try to start any queued instances for this workflow (called after an instance completes). */

package/dist/types/config.d.ts

@@ -124,3 +124,5 @@ export declare function loadConfig(path: string, envName?: string): Promise<Wran
  * Auto-detect config file in a directory. Tries wrangler.jsonc, wrangler.json, wrangler.toml.
  */
 export declare function autoLoadConfig(baseDir: string, envName?: string): Promise<WranglerConfig>;
+/** Resolve the wrangler config path under `baseDir` (jsonc | json | toml). */
+export declare function findConfigPath(baseDir: string): string;

package/dist/types/env.d.ts

@@ -57,4 +57,10 @@ export declare function buildEnv(config: WranglerConfig, devVarsDir?: string, ex
     registry: ClassRegistry;
 };
 export declare function wireClassRefs(registry: ClassRegistry, workerModule: Record<string, unknown>, env: Record<string, unknown>, workerRegistry?: WorkerRegistry, generationId?: number): void;
+/**
+ * Service-binding wiring extracted so thread-mode generations (which skip
+ * `wireClassRefs` entirely — DO/Workflow classes live in the worker) can
+ * still resolve cross-worker fetches through the registry.
+ */
+export declare function wireServiceBindings(registry: ClassRegistry, workerModule: Record<string, unknown>, env: Record<string, unknown>, workerRegistry?: WorkerRegistry): void;
 export {};

package/dist/types/error-page-render.d.ts

@@ -1,2 +1,8 @@
 import type { WranglerConfig } from './config';
+/**
+ * Stitch a captured caller stack onto a short async error so dev-time stacks
+ * show where the failing call originated. Mutates `err.stack` in place; no-op
+ * if either side is missing, already stitched, or `err.stack` looks deep.
+ */
+export declare function stitchAsyncStack(err: Error, callerError: Error | null): void;
 export declare function renderErrorPage(error: unknown, request: Request, env: Record<string, unknown>, config: WranglerConfig, workerName?: string): Promise<Response>;

package/dist/types/execution-context.d.ts

@@ -1,8 +1,16 @@
 export declare function getActiveExecutionContext(): ExecutionContext | undefined;
 export declare function runWithExecutionContext<T>(ctx: ExecutionContext, fn: () => T): T;
+/** Swallow + log a `waitUntil` rejection. Single source of truth for the log string.
+ *  Coerces non-thenables (CF tolerates `ctx.waitUntil(undefined)`) — a synchronous
+ *  throw here would strand the wait-until-settle accounting on the worker side. */
+export declare function logIfRejected(promise: Promise<unknown>): Promise<unknown>;
 export declare class ExecutionContext {
     private _promises;
     readonly props: Record<string, unknown>;
+    /** Cloudflare-compatible custom span API: `ctx.tracing.enterSpan(...)`. */
+    readonly tracing: {
+        enterSpan: typeof import("./tracing/span").enterSpan;
+    };
     constructor(props?: Record<string, unknown>);
     waitUntil(promise: Promise<unknown>): void;
     passThroughOnException(): void;

package/dist/types/generation-manager.d.ts

@@ -7,9 +7,20 @@ export declare class GenerationManager {
     private nextGenId;
     private _activeGenId;
     private _reloading;
-    private _pendingReload;
+    /** Coalesced follow-up: one reload queued to run after the in-flight one, with
+     *  its real promise handed to every caller that arrived during the in-flight
+     *  reload (so they observe the result/error of the reload reflecting their
+     *  request, not a stale `this.active`). */
+    private _pendingReloadPromise;
     /** DO namespaces shared across generations to preserve WebSocket connections on reload */
     private _doNamespaces;
+    /** Per-cron last-fired-minute dedup, shared across generations so a reload
+     *  mid-minute doesn't re-run a scheduled handler the previous generation already
+     *  fired (keyed by cron expression). */
+    private _cronLastFired;
+    /** Generation ids whose interrupted workflows have already been resumed, so a
+     *  generation isn't resumed twice (which would re-execute the same instances). */
+    private _resumedGenIds;
     gracePeriodMs: number;
     readonly config: WranglerConfig;
     readonly baseDir: string;
@@ -24,7 +35,7 @@ export declare class GenerationManager {
         executablePath?: string;
         headless?: boolean;
     } | undefined;
-    /** @internal Path to the wrangler config file (for isolated mode worker threads) */
+    /** @internal Path to the wrangler config file (DO worker threads re-load it). */
     _configPath: string;
     constructor(config: WranglerConfig, baseDir: string, options?: {
         workerName?: string;
@@ -47,6 +58,14 @@ export declare class GenerationManager {
      */
     reload(): Promise<Generation>;
     private _doReload;
+    /**
+     * Resume interrupted (running/waiting) workflow instances on `gen`'s worker,
+     * routed through the live worker-side binding. Guarded so a generation is
+     * resumed at most once even when several older generations stop in sequence —
+     * a second resume would re-execute the same instances (the bug this avoids).
+     */
+    private _resumeWorkflows;
+    private _scheduleDrainAndStop;
     private _stopGeneration;
     /** Force-drain a specific generation */
     drain(genId: number): void;

package/dist/types/generation.d.ts

@@ -1,7 +1,9 @@
+import { type Server } from 'bun';
 import type { DurableObjectNamespaceImpl } from './bindings/durable-object';
 import type { SqliteWorkflowBinding } from './bindings/workflow';
 import type { WranglerConfig } from './config';
-interface ClassRegistry {
+import type { WorkerThreadExecutor } from './worker-thread/executor';
+export interface ClassRegistry {
     durableObjects: {
         bindingName: string;
         className: string;
@@ -54,39 +56,32 @@ export declare class Generation {
     readonly id: number;
     state: GenerationState;
     readonly createdAt: number;
-    readonly workerModule: Record<string, unknown>;
-    readonly defaultExport: unknown;
-    readonly classBasedExport: boolean;
     readonly env: Record<string, unknown>;
     readonly registry: ClassRegistry;
     readonly config: WranglerConfig;
     readonly workerName: string | undefined;
     readonly cronEnabled: boolean;
+    readonly threadExecutor: WorkerThreadExecutor;
     activeRequests: number;
-    private queueConsumers;
     private cronTimer;
-    drainTimer: ReturnType<typeof setTimeout> | null;
-    drainPollTimer: ReturnType<typeof setInterval> | null;
-    constructor(id: number, workerModule: Record<string, unknown>, defaultExport: unknown, classBasedExport: boolean, env: Record<string, unknown>, registry: ClassRegistry, config: WranglerConfig, workerName?: string, cronEnabled?: boolean);
-    /** Get a handler method from the worker module (class-based or object-based) */
-    private getHandler;
-    /** Dispatch a fetch request through this generation's handler */
-    callFetch(request: Request, server: any): Promise<Response | undefined>;
+    constructor(id: number, env: Record<string, unknown>, registry: ClassRegistry, config: WranglerConfig, threadExecutor: WorkerThreadExecutor, workerName?: string, cronEnabled?: boolean);
+    /** Dispatch a fetch request through the worker thread. */
+    callFetch(request: Request, server: Server<unknown>): Promise<Response | undefined>;
+    private _dispatchFetch;
     /** Handle manual /cdn-cgi/handler/scheduled trigger */
     callScheduled(cronExpr: string): Promise<Response>;
     /** Handle incoming email — dispatches to the worker's email() handler */
     callEmail(rawBytes: Uint8Array, from: string, to: string): Promise<Response>;
-    /** Start queue consumers and cron scheduler */
-    startConsumers(): void;
-    /** Stop queue consumers and cron scheduler */
+    /** Start cron timer. Queue consumers run in the worker thread; no main-side action needed.
+     *  `cronLastFired` is the manager-owned per-minute dedup state, shared across
+     *  generations so a reload mid-minute doesn't re-fire a cron already handled. */
+    startConsumers(cronLastFired?: Map<string, number>): void;
+    private _persistAndRethrow;
     stopConsumers(): void;
-    /** Transition to draining — stops consumers, clears alarm timers, keeps in-flight requests alive */
-    drain(): void;
-    /** Force-stop: drain + destroy all DO namespaces + abort workflows */
+    /** Transition to draining — stops consumers + alarm timers, keeps in-flight requests alive. */
+    drain(sharedNamespaces?: Set<DurableObjectNamespaceImpl>): void;
+    /** Force-stop: drain + destroy all DO namespaces + abort workflows + terminate the worker. */
     stop(sharedNamespaces?: Set<DurableObjectNamespaceImpl>): void;
-    /** Check if this generation has no more work */
     isIdle(): boolean;
-    /** Get info for dashboard */
     getInfo(): GenerationInfo;
 }
-export {};

package/dist/types/import-graph.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Walk the worker's transitive import graph from `entry`, returning the set of
+ * absolute project-source paths it depends on (entry included). Anything that
+ * resolves outside `baseDir` or into `node_modules` is treated as external and
+ * not followed.
+ */
+export declare function collectImportGraph(entry: string, baseDir: string): Set<string>;
+/**
+ * Polls the worker's import graph for changes (mtime-based) and fires `onChange`.
+ * After a reload the caller should `rescan()` so newly-added imports start being
+ * watched (and deleted files stop being watched).
+ */
+export declare class ImportGraphWatcher {
+    private entry;
+    private baseDir;
+    private onChange;
+    private pollIntervalMs;
+    private mtimes;
+    private timer;
+    constructor(entry: string, baseDir: string, onChange: () => void, pollIntervalMs?: number);
+    start(): void;
+    stop(): void;
+    /** Recompute the watched set from the current import graph. */
+    rescan(): void;
+    /** Number of files currently watched (for the startup log line). */
+    get size(): number;
+    private poll;
+}

package/dist/types/lopata-config.d.ts

@@ -12,9 +12,9 @@ export interface LopataConfig {
     /** Enable real cron scheduling based on wrangler triggers.crons (default: false) */
     cron?: boolean;
     /**
-     * DO isolation mode:
-     * - "dev" (default) — all DO instances run in-process (fast, shared memory, hot reload)
-     * - "isolated" — each DO instance runs in a separate Bun Worker thread (faithful to CF production)
+     * @deprecated Has no effect. Workers and DO instances always run in their own
+     * Bun Worker thread now; the in-process path was removed. Kept only so existing
+     * configs don't fail to parse — see the deprecation warning in `cli/dev.ts`.
      */
     isolation?: 'dev' | 'isolated';
     /** AI SQL generation config for the D1 console */

package/dist/types/plugin.d.ts

@@ -1 +1,4 @@
-export {};
+/** The fetch handler registered via the legacy `addEventListener('fetch', …)`
+ *  service-worker syntax, if any. The worker-thread runtime falls back to this
+ *  when the module has no `export default { fetch }`. */
+export declare function getServiceWorkerFetchHandler(): ((event: unknown) => void) | undefined;

package/dist/types/rpc-validate.d.ts

@@ -14,3 +14,12 @@
 export declare function validateRpcValue(value: unknown, path?: string): string[];
 export declare function warnInvalidRpcArgs(args: unknown[], methodName: string): void;
 export declare function warnInvalidRpcReturn(value: unknown, methodName: string): void;
+/**
+ * Thread-mode pre-flight for RPC args. Functions and RpcTarget instances are
+ * VALID on real Cloudflare (they cross as callback / target stubs) and pass
+ * {@link validateRpcValue}, but they can't be structured-cloned across lopata's
+ * worker-thread boundary — `postMessage` throws an opaque DataCloneError with no
+ * guidance. Warn clearly (top-level args; the common `stub.method(cb)` case) so
+ * the dev knows why the call is about to fail.
+ */
+export declare function warnCrossThreadRpcArgs(args: unknown[], methodName: string): void;

package/dist/types/setup-globals.d.ts

@@ -2,7 +2,11 @@
  * Sets up global Cloudflare-compatible APIs:
  * caches, HTMLRewriter, WebSocketPair, IdentityTransformStream, FixedLengthStream,
  * navigator.userAgent, navigator.language, performance.timeOrigin, scheduler.wait(),
- * crypto extensions, and __lopata userland tracing API.
+ * and crypto extensions.
+ *
+ * Custom user spans are provided via the Cloudflare-native `tracing.enterSpan`
+ * API exported from `cloudflare:workers` (see src/virtual-modules.ts), not a
+ * Lopata-specific global.
  *
  * Idempotent — safe to call multiple times.
  */

package/dist/types/tracing/context.d.ts

@@ -4,6 +4,13 @@
 export interface FetchStackRef {
     current: Error | null;
 }
+/** Mutable subrequest counter shared across all spans in the same trace.
+ *  Scopes the binding subrequest budget to a single top-level request, the
+ *  way Cloudflare resets the budget per incoming request: a fresh ref is
+ *  minted at the root span and inherited by every child span. */
+export interface SubrequestCounterRef {
+    count: number;
+}
 export interface SpanContext {
     traceId: string;
     spanId: string;
@@ -13,9 +20,23 @@ export interface SpanContext {
      *  call still contains the user's code frames — we stitch it onto caught
      *  errors. */
     fetchStack: FetchStackRef;
+    /** Per-top-level-request subrequest counter, shared across the trace. */
+    subrequests: SubrequestCounterRef;
 }
 export declare function getActiveContext(): SpanContext | undefined;
 export declare function runWithContext<T>(ctx: SpanContext, fn: () => T): T;
+/**
+ * Adopt a parent (traceId + spanId) sent across an isolate boundary — refs
+ * (`fetchStack`, `subrequests`) can't cross postMessage, so we re-seed empty
+ * ones and let sub-spans created on this side share them via `getActiveContext`.
+ * Note: the per-request subrequest budget resets on each side of the boundary;
+ * a nested service-binding hop into another thread effectively gets a fresh
+ * budget. Acceptable for dev; a real fix would round-trip the count.
+ */
+export declare function runWithParentContext<T>(parent: {
+    traceId: string;
+    spanId: string;
+} | undefined, fn: () => T): T;
 export declare function generateId(byteCount?: number): string;
 /** Generate a 128-bit trace ID (OTel standard: 16 bytes / 32 hex chars) */
 export declare function generateTraceId(): string;

package/dist/types/tracing/span.d.ts

@@ -7,12 +7,30 @@ export interface SpanOptions {
     /** Force a new root trace, ignoring any active parent context. */
     newTrace?: boolean;
 }
+/** Handle passed to span callbacks, mirroring Cloudflare's custom-span Span object. */
+export interface SpanHandle {
+    /** Set an attribute on the span. Passing `undefined` is a no-op, matching Cloudflare (allows optional chaining). */
+    setAttribute(key: string, value: string | number | boolean | undefined): void;
+    /** Whether this invocation is being traced. Always true in lopata's dev runtime. */
+    readonly isTraced: boolean;
+}
 export declare function startSpan<T>(opts: SpanOptions, fn: () => T | Promise<T>): Promise<T>;
 /** Synchronous variant of startSpan for instrumenting non-async APIs (e.g. DO
- *  state.storage.sql.exec is sync). Inserts the span before fn() runs and ends
- *  it after, mirroring the async version's status/exception handling. fn is
- *  invoked inside runWithContext so any spans it creates nest correctly. */
+ *  state.storage.sql.exec is sync). The span ends as soon as fn returns; fn runs
+ *  inside the span context so any spans it creates nest correctly. */
 export declare function startSyncSpan<T>(opts: SpanOptions, fn: () => T): T;
+/**
+ * Cloudflare-compatible custom span API (`tracing.enterSpan` from `cloudflare:workers`, also
+ * `ctx.tracing`). Runs `fn` inside a child span of the active trace context, passing a span
+ * handle for `setAttribute` / `isTraced`. The callback's value is returned as-is (sync stays
+ * sync, async returns the promise) and the span auto-ends when the callback returns or its
+ * returned promise settles — matching Cloudflare's semantics.
+ */
+export declare function enterSpan<T>(name: string, fn: (span: SpanHandle) => T): T;
+/** Cloudflare-compatible `tracing` namespace exported from `cloudflare:workers` and exposed as `ctx.tracing`. */
+export declare const tracing: {
+    enterSpan: typeof enterSpan;
+};
 export declare function setSpanStatus(status: 'ok' | 'error', message?: string): void;
 export declare function setSpanAttribute(key: string, value: unknown): void;
 export declare function addSpanEvent(name: string, level: string, message: string, attrs?: Record<string, unknown>): void;

package/dist/types/tracing/store.d.ts

@@ -1,6 +1,15 @@
 import type { Database } from 'bun:sqlite';
 import type { SpanData, SpanEventData, TraceDetail, TraceEvent, TraceSummary } from './types';
 type Listener = (event: TraceEvent) => void;
+/**
+ * `JSON.stringify` for user-controlled span attributes / event payloads.
+ * Plain `JSON.stringify` THROWS on a `BigInt` and on a circular reference —
+ * both trivially reachable from user code (`setAttribute('x', 1n)`, logging a
+ * request/response object). In thread mode these writes run on the main thread
+ * (inside `worker.onmessage`), so an unguarded throw would take down the whole
+ * dev server. A dropped/coerced value is always preferable to a crash here.
+ */
+export declare function safeStringify(value: unknown): string;
 export declare class TraceStore {
     private db;
     private listeners;
@@ -126,4 +135,12 @@ export declare class TraceStore {
     private rowToSpan;
 }
 export declare function getTraceStore(): TraceStore;
+/** Override the process-wide default store. Used by tests to inject an in-memory DB. */
+export declare function setTraceStore(store: TraceStore | null): void;
+/**
+ * Swap the process-local trace store. Used by the worker-thread runtime to
+ * install a forwarding store. **Do not call from main** — that mutes the
+ * dashboard subscribers attached to the real store.
+ */
+export declare function setTraceStoreOverride(store: Pick<TraceStore, 'insertSpan' | 'endSpan' | 'setSpanStatus' | 'getSpanStatus' | 'updateAttributes' | 'addEvent' | 'insertError'> | null): void;
 export {};