lopata 0.18.3 → 0.19.0

package/src/import-graph.ts

@@ -0,0 +1,140 @@
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Import-graph watching for the dev server.
+ *
+ * The naive watcher polls a single directory (`dirname(config.main)`), which
+ * misses edits to code the worker imports from OUTSIDE that directory — e.g. an
+ * entry at `workers/app.ts` that imports handlers from `../app/**`. Because the
+ * worker-thread executor re-imports the WHOLE module graph on every reload, the
+ * only thing missing is the trigger: we just need to watch the files the worker
+ * actually depends on.
+ *
+ * We resolve that set statically with Bun's transpiler (`scanImports`) +
+ * `Bun.resolveSync`, following only project-local files (under `baseDir`, never
+ * `node_modules`). This needs no internal runtime registry (`globalThis.Loader`
+ * is gone in current Bun) and no bundler step.
+ *
+ * Caveat: a static scan cannot see fully-dynamic `import(variable)` targets. In
+ * practice worker entrypoints import statically; a dynamic target only fails to
+ * auto-reload until it is reached from a statically-imported file.
+ */
+
+/** Extensions we parse for further imports. Others (e.g. .json) are watched but not scanned. */
+const SCANNABLE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'])
+
+/**
+ * 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 function collectImportGraph(entry: string, baseDir: string): Set<string> {
+	const seen = new Set<string>()
+	const transpiler = new Bun.Transpiler({ loader: 'tsx' })
+	const root = baseDir.endsWith(path.sep) ? baseDir : baseDir + path.sep
+	const stack = [path.resolve(entry)]
+
+	while (stack.length > 0) {
+		const file = stack.pop()!
+		if (seen.has(file)) continue
+		seen.add(file)
+		if (!SCANNABLE.has(path.extname(file))) continue
+
+		let code: string
+		try {
+			code = readFileSync(file, 'utf8')
+		} catch {
+			continue
+		}
+		let imports: { path: string }[]
+		try {
+			imports = transpiler.scanImports(code)
+		} catch {
+			continue // unparseable file — skip its imports, still watch the file itself
+		}
+
+		const dir = path.dirname(file)
+		for (const imp of imports) {
+			let resolved: string
+			try {
+				resolved = Bun.resolveSync(imp.path, dir)
+			} catch {
+				continue // bare/builtin/unresolvable (node:*, external pkg) — not project source
+			}
+			// Follow only project-local files; never descend into dependencies.
+			if (!resolved.startsWith(root) || resolved.includes(`${path.sep}node_modules${path.sep}`)) continue
+			if (!seen.has(resolved)) stack.push(resolved)
+		}
+	}
+	return seen
+}
+
+/**
+ * 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 class ImportGraphWatcher {
+	private mtimes = new Map<string, number>()
+	private timer: ReturnType<typeof setInterval> | null = null
+
+	constructor(
+		private entry: string,
+		private baseDir: string,
+		private onChange: () => void,
+		private pollIntervalMs = 500,
+	) {}
+
+	start(): void {
+		if (this.timer) return
+		this.rescan()
+		this.timer = setInterval(() => this.poll(), this.pollIntervalMs)
+	}
+
+	stop(): void {
+		if (this.timer) {
+			clearInterval(this.timer)
+			this.timer = null
+		}
+	}
+
+	/** Recompute the watched set from the current import graph. */
+	rescan(): void {
+		const next = new Map<string, number>()
+		for (const file of collectImportGraph(this.entry, this.baseDir)) {
+			try {
+				next.set(file, statSync(file).mtimeMs)
+			} catch {
+				// vanished between scan and stat — drop it
+			}
+		}
+		this.mtimes = next
+	}
+
+	/** Number of files currently watched (for the startup log line). */
+	get size(): number {
+		return this.mtimes.size
+	}
+
+	private poll(): void {
+		let changed = false
+		for (const [file, prev] of this.mtimes) {
+			let mtime: number
+			try {
+				mtime = statSync(file).mtimeMs
+			} catch {
+				// deleted — a real change; refreshed on the next rescan()
+				this.mtimes.delete(file)
+				changed = true
+				continue
+			}
+			if (mtime !== prev) {
+				this.mtimes.set(file, mtime)
+				changed = true
+			}
+		}
+		if (changed) this.onChange()
+	}
+}

package/src/lopata-config.ts

@@ -15,9 +15,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/src/plugin.ts

@@ -22,6 +22,13 @@ Object.defineProperty(globalThis, 'addEventListener', {
 }) /** @internal Get the registered service worker fetch handler */
 ;(globalThis as any).__lopata_sw_handlers = _serviceWorkerHandlers
 
+/** 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 function getServiceWorkerFetchHandler(): ((event: unknown) => void) | undefined {
+	return _serviceWorkerHandlers.fetch
+}
+
 // ─── Console instrumentation ─────────────────────────────────────────
 // Captures console.log/info/warn/error/debug as span events when inside a trace context.
 

package/src/rpc-validate.ts

@@ -158,3 +158,32 @@ export function warnInvalidRpcReturn(value: unknown, methodName: string): void {
 		console.warn(`[lopata] RPC ${methodName}() return value warning: ${msg}`)
 	}
 }
+
+const RPC_TARGET_BRAND = Symbol.for('lopata.RpcTarget')
+
+function crossThreadUnsupportedKind(v: unknown): string | null {
+	if (typeof v === 'function') return 'a callback/function'
+	if (v && typeof v === 'object' && (v as Record<symbol, unknown>)[RPC_TARGET_BRAND] === true) return 'an RpcTarget'
+	return null
+}
+
+/**
+ * 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 function warnCrossThreadRpcArgs(args: unknown[], methodName: string): void {
+	for (let i = 0; i < args.length; i++) {
+		const kind = crossThreadUnsupportedKind(args[i])
+		if (kind) {
+			console.warn(
+				`[lopata] RPC ${methodName}() arg${i} is ${kind} — these can't cross lopata's worker-thread `
+					+ `boundary (they work as stubs on real Cloudflare). Pass plain data instead; the call will `
+					+ `otherwise fail with a DataCloneError.`,
+			)
+		}
+	}
+}

package/src/setup-globals.ts

@@ -6,7 +6,6 @@ import { HTMLRewriter } from './bindings/html-rewriter'
 import { WebSocketPair } from './bindings/websocket-pair'
 import { getDatabase } from './db'
 import { instrumentBinding } from './tracing/instrument'
-import { addSpanEvent, setSpanAttribute, startSpan } from './tracing/span'
 
 let initialized = false
 
@@ -14,27 +13,17 @@ let initialized = false
  * 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.
  */
 export function setupCloudflareGlobals() {
 	if (initialized) return
-	initialized = true // ─── Userland tracing API ────────────────────────────────────────────
-	 // Exposes a lightweight global that user code can call to create custom
-	// spans visible in the Lopata dashboard.  In production (without Lopata)
-	// the global is simply absent, so the user's thin wrapper becomes a no-op.
-	;(globalThis as any).__lopata = {
-		trace<T>(name: string, attrsOrFn: Record<string, unknown> | (() => T | Promise<T>), maybeFn?: () => T | Promise<T>): Promise<T> {
-			const fn = typeof attrsOrFn === 'function' ? attrsOrFn : maybeFn!
-			const attributes = typeof attrsOrFn === 'function' ? undefined : attrsOrFn
-			return startSpan({ name, attributes }, fn)
-		},
-		setAttribute: setSpanAttribute,
-		addEvent(name: string, message?: string, attrs?: Record<string, unknown>): void {
-			addSpanEvent(name, 'info', message ?? '', attrs)
-		},
-	}
+	initialized = true
 
 	// Register global `caches` object (CacheStorage) with tracing.
 	// Lazy: only creates the SqliteCacheStorage (and its getDatabase() call) on first access.

package/src/testing/durable-object.ts

@@ -272,10 +272,12 @@ export class TestDurableObjectHandle {
 			throw new Error('DO fetch handler did not return a WebSocket upgrade response (no response.webSocket)')
 		}
 
-		// Accept the client side (simulates what Bun.serve does)
+		// Build the TestWebSocket FIRST so its message/close listeners are
+		// registered before `accept()` flushes any events the DO already queued
+		// (e.g. `server.send(...)` issued before the response was returned).
+		const tw = new TestWebSocket(serverWs)
 		serverWs.accept()
-
-		return new TestWebSocket(serverWs)
+		return tw
 	}
 
 	/** Get all accepted WebSockets for this DO instance (via DurableObjectState). */

package/src/testing/index.ts

@@ -101,11 +101,13 @@ export async function createTestEnv<Env = Record<string, unknown>>(options: Test
 		entry.binding.resumeInterrupted()
 	}
 
-	// Wire service bindings — self-referencing
+	// Wire service bindings — self-referencing (always in-process for tests)
 	for (const entry of registry.serviceBindings) {
-		const wire = entry.proxy._wire as ((resolver: () => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) => void) | undefined
+		const wire = entry.proxy._wire as
+			| ((resolver: () => { kind: 'in-process'; workerModule: Record<string, unknown>; env: Record<string, unknown> }) => void)
+			| undefined
 		if (wire) {
-			wire(() => ({ workerModule, env }))
+			wire(() => ({ kind: 'in-process', workerModule, env }))
 		}
 	}
 
@@ -254,7 +256,9 @@ export async function createTestEnv<Env = Record<string, unknown>>(options: Test
 		for (const tw of testWorkflows) tw.dispose()
 		for (const td of testDOs) td.dispose()
 		for (const entry of registry.durableObjects) {
-			entry.namespace.destroy()
+			// force: final teardown — dispose every executor and leave no eviction
+			// timer running past db.close() below.
+			entry.namespace.destroy({ force: true })
 		}
 		for (const entry of registry.workflows) {
 			entry.binding.abortRunning()

package/src/tracing/context.ts

@@ -7,6 +7,14 @@ 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
@@ -16,6 +24,8 @@ 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
 }
 
 const storage = new AsyncLocalStorage<SpanContext>()
@@ -28,6 +38,24 @@ export function runWithContext<T>(ctx: SpanContext, fn: () => T): T {
 	return storage.run(ctx, fn)
 }
 
+/**
+ * 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 function runWithParentContext<T>(parent: { traceId: string; spanId: string } | undefined, fn: () => T): T {
+	if (!parent) return fn()
+	return storage.run({
+		traceId: parent.traceId,
+		spanId: parent.spanId,
+		fetchStack: { current: null },
+		subrequests: { count: 0 },
+	}, fn)
+}
+
 export function generateId(byteCount = 8): string {
 	const bytes = new Uint8Array(byteCount)
 	crypto.getRandomValues(bytes)

package/src/tracing/span.ts

@@ -1,6 +1,6 @@
 import { generateId, generateTraceId, getActiveContext, runWithContext } from './context'
 import { buildErrorFrames } from './frames'
-import { getTraceStore } from './store'
+import { getTraceStore, type TraceStore } from './store'
 import type { SpanData } from './types'
 
 export interface SpanOptions {
@@ -12,7 +12,28 @@ export interface SpanOptions {
 	newTrace?: boolean
 }
 
-export async function startSpan<T>(opts: SpanOptions, fn: () => T | Promise<T>): Promise<T> {
+/** 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
+}
+
+interface SpanRunOptions extends SpanOptions {
+	/** Internal hook: inspect a successful result before the span's final status is computed,
+	 *  so it can flag a failure (used by startSpan to mark an HTTP 5xx Response errored). */
+	onSuccess?: (result: unknown, spanId: string, store: TraceStore) => void
+}
+
+/**
+ * Core span runner shared by startSpan / startSyncSpan / enterSpan. Creates a child span of
+ * the active context (or a new root when `newTrace`), runs `fn` inside it, and ends the span
+ * when `fn` returns or — if it returned a thenable — when that promise settles. The result is
+ * returned as-is: synchronous callbacks stay synchronous, async ones return the promise. On a
+ * thrown/rejected error the span is marked errored and an `exception` event is recorded.
+ */
+function runInSpan<T>(opts: SpanRunOptions, fn: (span: SpanHandle) => T): T {
 	const store = getTraceStore()
 	const parent = opts.newTrace ? undefined : getActiveContext()
 
@@ -34,23 +55,33 @@ export async function startSpan<T>(opts: SpanOptions, fn: () => T | Promise<T>):
 		attributes: opts.attributes ?? {},
 		workerName: opts.workerName ?? null,
 	}
-
 	store.insertSpan(span)
 
 	// Share fetchStack ref across all spans in the same trace so that
 	// fetch call-site stacks captured in sub-spans are visible in the root
 	// span's error handler.
 	const fetchStack = parent?.fetchStack ?? { current: null }
+	// Subrequest budget is per top-level request: a root span (no parent) mints
+	// a fresh counter; child spans inherit it. This resets the budget on each
+	// incoming request, matching Cloudflare — instead of leaking across the
+	// whole dev-server lifetime.
+	const subrequests = parent?.subrequests ?? { count: 0 }
+
+	const handle: SpanHandle = {
+		setAttribute(key, value) {
+			if (value === undefined) return
+			store.updateAttributes(spanId, { [key]: value })
+		},
+		isTraced: true,
+	}
 
-	try {
-		const result = await runWithContext({ traceId, spanId, fetchStack }, () => fn())
-		if (result instanceof Response && result.status >= 500) {
-			store.setSpanStatus(spanId, 'error', `HTTP ${result.status}`)
-		}
+	const succeed = (result: unknown): void => {
+		opts.onSuccess?.(result, spanId, store)
 		const currentStatus = store.getSpanStatus(spanId)
 		store.endSpan(spanId, Date.now(), currentStatus === 'error' ? 'error' : 'ok')
-		return result
-	} catch (err) {
+	}
+
+	const fail = (err: unknown): void => {
 		const message = err instanceof Error ? err.message : String(err)
 		store.endSpan(spanId, Date.now(), 'error', message)
 		store.addEvent({
@@ -62,61 +93,62 @@ export async function startSpan<T>(opts: SpanOptions, fn: () => T | Promise<T>):
 			message,
 			attributes: err instanceof Error ? { stack: err.stack } : {},
 		})
-		throw err
 	}
-}
-
-/** 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. */
-export function startSyncSpan<T>(opts: SpanOptions, fn: () => T): T {
-	const store = getTraceStore()
-	const parent = opts.newTrace ? undefined : getActiveContext()
-
-	const spanId = generateId()
-	const traceId = parent?.traceId ?? generateTraceId()
-	const parentSpanId = parent?.spanId ?? null
-
-	const span: SpanData = {
-		spanId,
-		traceId,
-		parentSpanId,
-		name: opts.name,
-		kind: opts.kind ?? 'internal',
-		status: 'unset',
-		statusMessage: null,
-		startTime: Date.now(),
-		endTime: null,
-		durationMs: null,
-		attributes: opts.attributes ?? {},
-		workerName: opts.workerName ?? null,
-	}
-
-	store.insertSpan(span)
-	const fetchStack = parent?.fetchStack ?? { current: null }
 
 	try {
-		const result = runWithContext({ traceId, spanId, fetchStack }, fn)
-		const currentStatus = store.getSpanStatus(spanId)
-		store.endSpan(spanId, Date.now(), currentStatus === 'error' ? 'error' : 'ok')
+		const result = runWithContext({ traceId, spanId, fetchStack, subrequests }, () => fn(handle))
+		if (result != null && typeof (result as { then?: unknown }).then === 'function') {
+			return (result as unknown as Promise<unknown>).then(
+				value => {
+					succeed(value)
+					return value
+				},
+				err => {
+					fail(err)
+					throw err
+				},
+			) as T
+		}
+		succeed(result)
 		return result
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err)
-		store.endSpan(spanId, Date.now(), 'error', message)
-		store.addEvent({
-			spanId,
-			traceId,
-			timestamp: Date.now(),
-			name: 'exception',
-			level: 'error',
-			message,
-			attributes: err instanceof Error ? { stack: err.stack } : {},
-		})
+		fail(err)
 		throw err
 	}
 }
 
+/** Flags a span errored when the handler returned an HTTP 5xx Response. */
+function flagServerErrorStatus(result: unknown, spanId: string, store: TraceStore): void {
+	if (result instanceof Response && result.status >= 500) {
+		store.setSpanStatus(spanId, 'error', `HTTP ${result.status}`)
+	}
+}
+
+export async function startSpan<T>(opts: SpanOptions, fn: () => T | Promise<T>): Promise<T> {
+	return runInSpan<T | Promise<T>>({ ...opts, onSuccess: flagServerErrorStatus }, () => fn())
+}
+
+/** Synchronous variant of startSpan for instrumenting non-async APIs (e.g. DO
+ *  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 function startSyncSpan<T>(opts: SpanOptions, fn: () => T): T {
+	return runInSpan<T>(opts, () => fn())
+}
+
+/**
+ * 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 function enterSpan<T>(name: string, fn: (span: SpanHandle) => T): T {
+	return runInSpan<T>({ name }, fn)
+}
+
+/** Cloudflare-compatible `tracing` namespace exported from `cloudflare:workers` and exposed as `ctx.tracing`. */
+export const tracing = { enterSpan }
+
 export function setSpanStatus(status: 'ok' | 'error', message?: string): void {
 	const ctx = getActiveContext()
 	if (!ctx) return

package/src/tracing/store.ts

@@ -4,6 +4,26 @@ import type { SpanData, SpanEventData, TraceDetail, TraceEvent, TraceSummary } f
 
 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 function safeStringify(value: unknown): string {
+	const seen = new WeakSet<object>()
+	return JSON.stringify(value, (_key, val) => {
+		if (typeof val === 'bigint') return val.toString()
+		if (typeof val === 'object' && val !== null) {
+			if (seen.has(val)) return '[Circular]'
+			seen.add(val)
+		}
+		return val
+	})
+}
+
 const TRACE_CAP = 10_000
 const PRUNE_BATCH = 100
 const STALE_SPAN_TTL_MS = 10 * 60 * 1000 // 10 minutes
@@ -80,7 +100,7 @@ export class TraceStore {
 			span.startTime,
 			span.endTime,
 			span.durationMs,
-			JSON.stringify(span.attributes),
+			safeStringify(span.attributes),
 			span.workerName,
 		)
 		this.broadcast({ type: 'span.start', span })
@@ -113,7 +133,7 @@ export class TraceStore {
 	}
 
 	updateAttributes(spanId: string, attrs: Record<string, unknown>): void {
-		this.updateAttributesStmt.run(JSON.stringify(attrs), spanId)
+		this.updateAttributesStmt.run(safeStringify(attrs), spanId)
 	}
 
 	addEvent(event: Omit<SpanEventData, 'id'>): void {
@@ -124,7 +144,7 @@ export class TraceStore {
 			event.name,
 			event.level,
 			event.message,
-			JSON.stringify(event.attributes),
+			safeStringify(event.attributes),
 		)
 		const id = this.db.prepare<{ id: number }, []>('SELECT last_insert_rowid() as id').get()?.id
 		this.broadcast({ type: 'span.event', event: { ...event, id } })
@@ -589,10 +609,28 @@ function parseCursor(cursor?: string): { time: number; id: string } {
 }
 
 let defaultStore: TraceStore | null = null
+let overrideStore: TraceStore | null = null
 
 export function getTraceStore(): TraceStore {
+	if (overrideStore) return overrideStore
 	if (!defaultStore) {
 		defaultStore = new TraceStore()
 	}
 	return defaultStore
 }
+
+/** Override the process-wide default store. Used by tests to inject an in-memory DB. */
+export function setTraceStore(store: TraceStore | null): void {
+	defaultStore = store
+}
+
+/**
+ * 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 function setTraceStoreOverride(
+	store: Pick<TraceStore, 'insertSpan' | 'endSpan' | 'setSpanStatus' | 'getSpanStatus' | 'updateAttributes' | 'addEvent' | 'insertError'> | null,
+): void {
+	overrideStore = store as TraceStore | null
+}

package/src/virtual-modules.ts

@@ -7,6 +7,7 @@ import { WebSocketPair } from './bindings/websocket-pair'
 import { NonRetryableError, WorkflowEntrypointBase } from './bindings/workflow'
 import { globalEnv } from './env'
 import { getActiveExecutionContext } from './execution-context'
+import { tracing } from './tracing/span'
 
 /**
  * Registers virtual modules for `cloudflare:workers`, `cloudflare:workflows`,
@@ -43,6 +44,7 @@ export function registerVirtualModules(build: { module: (name: string, fn: () =>
 						ctx.waitUntil(promise)
 					}
 				},
+				tracing,
 			},
 			loader: 'object',
 		}

package/src/vite-plugin/dev-server-plugin.ts

@@ -389,6 +389,10 @@ export function devServerPlugin(options: DevServerPluginOptions): Plugin {
 					auxConfigs.set(workerDef.configPath, { config: auxConfig, name: workerName })
 					console.log(`[lopata:vite] Auxiliary worker: ${workerName}`)
 
+					// Aux workers run in their own Bun Worker thread (GenerationManager's
+					// universal model) loaded via native Bun import — NOT through Vite's
+					// SSR/transform pipeline like the main worker. See `auxiliaryWorkers`
+					// in index.ts: author them as plain Bun-resolvable modules.
 					const auxManager = new GenerationManager(auxConfig, auxBaseDir, {
 						workerName,
 						workerRegistry,

package/src/vite-plugin/index.ts

@@ -12,7 +12,14 @@ export interface LopataPluginConfig {
 	viteEnvironment?: { name?: string }
 	/** Host patterns that route to the main worker (takes priority over wildcard auxiliary hosts). */
 	hosts?: string[]
-	/** Auxiliary workers loaded via native Bun import (not through Vite). */
+	/**
+	 * Auxiliary workers. Unlike the main worker (which runs in-process via Vite
+	 * SSR), each aux worker runs in its own Bun Worker thread and is loaded via
+	 * native Bun import — it does NOT go through Vite's transform pipeline
+	 * (aliases, `import.meta.glob`, env replacement, plugins). Intended for
+	 * workers reached over a service binding (APIs, queue/cron consumers) that
+	 * don't rely on Vite transforms; author them as plain Bun-resolvable modules.
+	 */
 	auxiliaryWorkers?: { configPath: string; name?: string; hosts?: string[] }[]
 }