@powerhousedao/switchboard 6.2.2-dev.2 → 6.2.2-dev.21

package/dist/{server-DgBz3TJW.mjs → server-ChK0GLG8.mjs}

@@ -1,19 +1,19 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8a8055ab-2ceb-59fe-9007-f1d1fde8a019")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b1867ed0-059f-587c-9a5f-677da3666de7")}catch(e){}}();
 import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-Baw7rThP.mjs";
 import { register } from "node:module";
 import * as Sentry from "@sentry/node";
 import { childLogger, documentModelDocumentModelModule, setLogLevel } from "document-model";
 import dotenv from "dotenv";
 import { getConfig } from "@powerhousedao/config/node";
-import { promises } from "node:fs";
+import { existsSync, promises, realpathSync } from "node:fs";
 import path from "node:path";
 import { ReactorInstrumentation } from "@powerhousedao/opentelemetry-instrumentation-reactor";
 import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
-import { ChannelScheme, DriveCollectionId, EventBus, REACTOR_SCHEMA, ReactorBuilder, ReactorClientBuilder, parseDriveUrl } from "@powerhousedao/reactor";
+import { ChannelScheme, DriveCollectionId, EventBus, REACTOR_SCHEMA, ReactorBuilder, ReactorClientBuilder, parseDriveUrl, supportsLiveReadModelRegistration } from "@powerhousedao/reactor";
 import { HttpPackageLoader, ImportPackageLoader, PackageManagementService, PackagesSubgraph, getUniqueDocumentModels, initializeAndStartAPI } from "@powerhousedao/reactor-api";
 import { httpsHooksPath } from "@powerhousedao/reactor-api/https-hooks";
-import { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, HashMismatch, InvalidAttachmentRef, ReservationNotFound, SizeMismatch, UploadTooLarge, createRemoteAttachmentService } from "@powerhousedao/reactor-attachments";
+import { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, AttachmentReferenceReadModel, AttachmentSchemaCompiler, HashMismatch, InvalidAttachmentRef, ReservationNotFound, SizeMismatch, UploadTooLarge, createRef, createRemoteAttachmentService, parseAttachmentDownloadTarget } from "@powerhousedao/reactor-attachments";
 import { DriveNodeView, NodeProcessor, ReactorDriveClient, createReactorDriveResolvers, reactorDriveDocumentModelModule, reactorDriveSubgraphTypeDefs } from "@powerhousedao/reactor-drive";
 import { Kysely, PostgresDialect } from "kysely";
 import net from "node:net";
@@ -21,6 +21,9 @@ import path$1 from "path";
 import { Pool } from "pg";
 import { Readable } from "node:stream";
 import { driveDocumentModelModule } from "@powerhousedao/shared/document-drive";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { EnvVarProvider } from "@openfeature/env-var-provider";
 import { OpenFeature } from "@openfeature/server-sdk";
 import { PGliteDialect } from "kysely-pglite-dialect";
@@ -61,13 +64,20 @@ async function loadPgDump(major) {
 }
 //#endregion
 //#region src/attachments/auth.ts
+const ANONYMOUS_ACTOR = {
+	user: void 0,
+	authEnabled: false
+};
 /**
 * Wrap a Node-style handler so that, when `authService` is provided and auth is
-* enabled, the request must carry a verifiable Bearer token.
+* enabled, the request must carry a verifiable Bearer token. The handler always
+* receives an actor context: the verified bearer user when auth is enabled, or
+* the anonymous context when it is disabled. With `allowAnonymous`, a missing
+* bearer yields an anonymous actor with `authEnabled: true` instead of a 401.
 */
-function requireAuth(authService, handler) {
-	if (!authService) return handler;
-	return async (req, res) => {
+function requireAuth(authService, handler, options) {
+	if (!authService) return (req, res, body) => handler(req, res, body, ANONYMOUS_ACTOR);
+	return async (req, res, body) => {
 		let result;
 		try {
 			result = await authService.verifyBearer(req.headers.authorization);
@@ -85,25 +95,32 @@ function requireAuth(authService, handler) {
 			res.end(body);
 			return;
 		}
-		if (result.auth_enabled && !result.user) {
+		if (result.auth_enabled && !result.user && !options?.allowAnonymous) {
 			res.statusCode = 401;
 			res.setHeader("Content-Type", "application/json");
 			res.end(JSON.stringify({ error: "Authentication required" }));
 			return;
 		}
-		await handler(req, res);
+		await handler(req, res, body, {
+			user: result.user,
+			authEnabled: result.auth_enabled
+		});
 	};
 }
 //#endregion
 //#region src/attachments/mount-auth.ts
 /**
 * Mount a Node-style attachment route with `requireAuth` applied unconditionally.
-* When `api.authService` is undefined (auth disabled), `requireAuth` returns the
-* handler unchanged — that is the only way to opt out. To register a route
-* without auth wrapping you must call `api.httpAdapter.mountNodeRoute` directly.
+* When `api.authService` is undefined (auth disabled), the handler still runs
+* through `requireAuth` and receives the anonymous actor context — that is the
+* only way to opt out of bearer verification. To register a route without auth
+* wrapping you must call `api.httpAdapter.mountNodeRoute` directly.
+*
+* `allowAnonymous` is reserved for routes whose handlers make a per-document
+* authorization decision themselves; identity-only routes must not use it.
 */
-function mountAuthenticatedNodeRoute(api, method, path, handler) {
-	api.httpAdapter.mountNodeRoute(method, path, requireAuth(api.authService, handler));
+function mountAuthenticatedNodeRoute(api, method, path, handler, options) {
+	api.httpAdapter.mountNodeRoute(method, path, requireAuth(api.authService, handler, options));
 }
 //#endregion
 //#region src/attachments/routes.ts
@@ -213,7 +230,8 @@ function makeReserveHandler(attachments) {
 		sendJson(res, 201, {
 			reservationId: upload.reservationId,
 			ref: upload.ref,
-			expiresAtUtc: upload.expiresAtUtc
+			expiresAtUtc: upload.expiresAtUtc,
+			...upload.uploadTarget ? { uploadTarget: upload.uploadTarget } : {}
 		});
 	};
 }
@@ -224,6 +242,10 @@ function makeUploadHandler(attachments) {
 			sendError(res, 400, "Missing reservationId");
 			return;
 		}
+		if (attachments.backend?.kind === "s3") {
+			sendError(res, 405, "Use the reservation uploadTarget for S3 uploads");
+			return;
+		}
 		let reservation;
 		try {
 			reservation = await attachments.reservations.get(reservationId);
@@ -370,6 +392,144 @@ function makeDeleteReservationHandler(attachments) {
 function extractParam(req, name) {
 	return req.params?.[name];
 }
+const MAX_DOCUMENT_ID_LEN = 512;
+const ATTACHMENT_NOT_FOUND_BODY = { error: "Attachment not found" };
+const MAX_DOWNLOAD_TARGET_TTL_SECONDS = 10080 * 60;
+/**
+* Returns the single `documentId` query value, or null when it is missing,
+* duplicated, blank, or oversized. Validation happens before authorization so
+* malformed requests never reach the access service.
+*/
+function extractSingleDocumentId(req) {
+	if (!req.url) return null;
+	let url;
+	try {
+		url = new URL(req.url, "http://switchboard.invalid");
+	} catch {
+		return null;
+	}
+	const values = url.searchParams.getAll("documentId");
+	if (values.length !== 1) return null;
+	const value = values[0];
+	if (value.trim().length === 0 || value.length > MAX_DOCUMENT_ID_LEN) return null;
+	return value;
+}
+/**
+* Returns the requested target TTL in seconds: undefined when absent,
+* "invalid" when malformed (duplicated, non-integer, or non-positive), and
+* otherwise the value clamped to the presigning ceiling.
+*/
+function extractExpiresIn(req) {
+	if (!req.url) return void 0;
+	let url;
+	try {
+		url = new URL(req.url, "http://switchboard.invalid");
+	} catch {
+		return;
+	}
+	const values = url.searchParams.getAll("expiresIn");
+	if (values.length === 0) return void 0;
+	if (values.length > 1) return "invalid";
+	const parsed = Number(values[0]);
+	if (!Number.isInteger(parsed) || parsed <= 0) return "invalid";
+	return Math.min(parsed, MAX_DOWNLOAD_TARGET_TTL_SECONDS);
+}
+/**
+* Base URL of this Switchboard as seen by the caller, used to build
+* filesystem `switchboard` download targets that point back at the existing
+* authenticated byte route.
+*/
+function requestBaseUrl(req) {
+	const forwardedProto = req.headers["x-forwarded-proto"];
+	const proto = (Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto)?.split(",")[0]?.trim() || (req.socket.encrypted ? "https" : "http");
+	const forwardedHost = req.headers["x-forwarded-host"];
+	const host = (Array.isArray(forwardedHost) ? forwardedHost[0] : forwardedHost) ?? req.headers.host;
+	if (!host) return null;
+	return `${proto}://${host}`;
+}
+function makeDownloadTargetHandler(attachments, attachmentAccess) {
+	return async (req, res, _body, actor) => {
+		res.setHeader("Cache-Control", "no-store");
+		const hash = extractParam(req, "hash");
+		if (!hash || !HASH_PATTERN.test(hash)) {
+			sendError(res, 400, "Invalid attachment hash");
+			return;
+		}
+		const documentId = extractSingleDocumentId(req);
+		if (documentId === null) {
+			sendError(res, 400, "documentId is required exactly once as a non-empty query parameter");
+			return;
+		}
+		const expiresIn = extractExpiresIn(req);
+		if (expiresIn === "invalid") {
+			sendError(res, 400, "expiresIn must be a single positive integer number of seconds");
+			return;
+		}
+		const canonicalHash = hash.toLowerCase();
+		let decision;
+		try {
+			decision = await attachmentAccess.canReadAttachment({
+				documentId,
+				attachmentRef: createRef(canonicalHash),
+				userAddress: actor?.user?.address
+			});
+		} catch (err) {
+			logger$1.error("Attachment access decision failed: @error", err);
+			sendError(res, 500, "Internal error");
+			return;
+		}
+		if (decision.kind === "projection-unavailable") {
+			sendError(res, 503, "Attachment downloads are temporarily unavailable");
+			return;
+		}
+		if (decision.kind === "denied") {
+			sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+			return;
+		}
+		let header;
+		try {
+			header = await attachments.store.stat(canonicalHash);
+		} catch (err) {
+			if (err instanceof AttachmentNotFound) {
+				sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+				return;
+			}
+			logger$1.error("Attachment metadata lookup failed: @error", err);
+			sendError(res, 500, "Internal error");
+			return;
+		}
+		if (header.status !== "available") {
+			sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+			return;
+		}
+		let target;
+		if (attachments.backend && attachments.backend.kind !== "filesystem") try {
+			target = await attachments.backend.prepareDownloadTarget(canonicalHash, expiresIn);
+		} catch {
+			sendError(res, 502, "Attachment download target unavailable");
+			return;
+		}
+		else {
+			const base = requestBaseUrl(req);
+			if (!base) {
+				sendError(res, 500, "Internal error");
+				return;
+			}
+			try {
+				target = parseAttachmentDownloadTarget({
+					kind: "switchboard",
+					method: "GET",
+					url: `${base}/attachments/${canonicalHash}`,
+					headers: {}
+				});
+			} catch {
+				sendError(res, 500, "Internal error");
+				return;
+			}
+		}
+		sendJson(res, 200, target);
+	};
+}
 //#endregion
 //#region src/attachments/index.ts
 function registerAttachmentRoutes(api) {
@@ -379,9 +539,50 @@ function registerAttachmentRoutes(api) {
 	mountAuthenticatedNodeRoute(api, "DELETE", "/attachments/reservations/:reservationId", makeDeleteReservationHandler(attachments));
 	mountAuthenticatedNodeRoute(api, "PUT", "/attachments/reservations/:reservationId", makeUploadHandler(attachments));
 	mountAuthenticatedNodeRoute(api, "HEAD", "/attachments/:hash", makeStatHandler(attachments));
+	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash/download-target", makeDownloadTargetHandler(attachments, api.attachmentAccess), { allowAnonymous: true });
 	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash", makeDownloadHandler(attachments));
 }
 //#endregion
+//#region src/attachment-reference-read-model.mts
+const attachmentSchemaCompiler = new AttachmentSchemaCompiler();
+function createAttachmentReferenceReadModel(baseKysely, dependencies, attachmentReferenceWriter) {
+	return new AttachmentReferenceReadModel(baseKysely.withSchema(REACTOR_SCHEMA), dependencies.operationIndex, dependencies.writeCache, dependencies.processorManagerConsistencyTracker, dependencies.documentModelRegistry, attachmentSchemaCompiler, attachmentReferenceWriter);
+}
+function registerAttachmentReferenceReadModel(reactorBuilder, registration) {
+	reactorBuilder.withReadModelFactory(async ({ documentModelRegistry, operationIndex, writeCache, processorManagerConsistencyTracker }) => {
+		const readModel = createAttachmentReferenceReadModel(registration.baseKysely, {
+			operationIndex,
+			writeCache,
+			processorManagerConsistencyTracker,
+			documentModelRegistry
+		}, registration.attachmentReferenceWriter);
+		await readModel.init();
+		return readModel;
+	});
+}
+async function registerAttachmentReferenceReadModelOnModule(clientModule, attachmentReferenceWriter) {
+	const reactorModule = clientModule.reactorModule;
+	if (!reactorModule) return {
+		status: "unavailable",
+		reason: "in-process-reactor-module-unavailable"
+	};
+	const coordinator = reactorModule.readModelCoordinator;
+	if (!supportsLiveReadModelRegistration(coordinator)) return {
+		status: "unavailable",
+		reason: "live-read-model-registration-unsupported"
+	};
+	const readModel = createAttachmentReferenceReadModel(reactorModule.database, {
+		operationIndex: reactorModule.operationIndex,
+		writeCache: reactorModule.writeCache,
+		processorManagerConsistencyTracker: reactorModule.processorManagerConsistencyTracker,
+		documentModelRegistry: reactorModule.documentModelRegistry
+	}, attachmentReferenceWriter);
+	await readModel.init();
+	coordinator.addReadModel(readModel, "pre_ready");
+	await readModel.init();
+	return { status: "available" };
+}
+//#endregion
 //#region src/builder-defaults.mts
 /**
 * Apply switchboard's standard configuration to a reactor + client builder
@@ -392,14 +593,18 @@ function registerAttachmentRoutes(api) {
 * Does NOT touch kysely or read models — callers wire those themselves
 * (see `withKysely` / `withReadModelFactory` on the reactor builder).
 */
-function applySwitchboardReactorDefaults(reactorBuilder, clientBuilder, options = {}) {
-	const baseModels = options.includeBaseModels !== false ? [
+/** The models switchboard always registers alongside package models. */
+function switchboardBaseDocumentModels() {
+	return [
 		documentModelDocumentModelModule,
 		driveDocumentModelModule,
 		reactorDriveDocumentModelModule
-	] : [];
+	];
+}
+function applySwitchboardReactorDefaults(reactorBuilder, clientBuilder, options = {}) {
+	const baseModels = options.includeBaseModels !== false ? switchboardBaseDocumentModels() : [];
 	const extra = options.documentModels ?? [];
-	if (baseModels.length || extra.length) reactorBuilder.withDocumentModels(getUniqueDocumentModels(baseModels, extra));
+	if (baseModels.length || extra.length) reactorBuilder.withDocumentModelSources(getUniqueDocumentModels(baseModels, extra));
 	const scheme = options.channelScheme === void 0 ? ChannelScheme.SWITCHBOARD : options.channelScheme;
 	if (scheme !== false) reactorBuilder.withChannelScheme(scheme);
 	if (options.signalHandlers !== false) reactorBuilder.withSignalHandlers();
@@ -409,6 +614,188 @@ function applySwitchboardReactorDefaults(reactorBuilder, clientBuilder, options
 	if (options.signer) clientBuilder.withSigner(options.signer);
 }
 //#endregion
+//#region src/worker-pool.mts
+const DEFAULT_DB_POOL_SIZE_PER_WORKER = 2;
+const DEFAULT_ACQUIRE_TIMEOUT_MS = 5e3;
+const AUTO_RESERVED_CORES = 2;
+const AUTO_WORKER_CAP = 8;
+/** Worker count for "auto": always at least 1 — auto sizes the pool, it does not turn worker mode off. */
+function autoWorkerCount(availableCores) {
+	return Math.max(1, Math.min(AUTO_WORKER_CAP, availableCores - AUTO_RESERVED_CORES));
+}
+/**
+* Effective worker-pool config from programmatic options (which win) and the
+* REACTOR_* env vars; null when disabled (numWorkers 0, the default).
+* `"auto"` sizes the pool from the machine's available cores.
+*/
+function resolveWorkerPoolOptions(input, env, availableCores = os.availableParallelism()) {
+	const requested = input?.numWorkers ?? parseWorkerCount(env.REACTOR_WORKERS) ?? 0;
+	const mode = requested === "auto" ? "auto" : "explicit";
+	const numWorkers = requested === "auto" ? autoWorkerCount(availableCores) : requested;
+	if (!Number.isInteger(numWorkers) || numWorkers < 0) throw new Error(`workerPool.numWorkers must be "auto" or a non-negative integer, got ${numWorkers}`);
+	if (numWorkers === 0) return null;
+	return {
+		numWorkers,
+		mode,
+		dbPoolSizePerWorker: input?.dbPoolSizePerWorker ?? parseNonNegativeInt(env.REACTOR_DB_POOL_SIZE_WORKER, "REACTOR_DB_POOL_SIZE_WORKER") ?? DEFAULT_DB_POOL_SIZE_PER_WORKER,
+		acquireTimeoutMs: input?.acquireTimeoutMs ?? parseNonNegativeInt(env.REACTOR_DB_ACQUIRE_TIMEOUT_MS, "REACTOR_DB_ACQUIRE_TIMEOUT_MS") ?? DEFAULT_ACQUIRE_TIMEOUT_MS
+	};
+}
+/**
+* DbConfig for each worker's own pool, parsed from a postgres:// URL.
+* Explicit host, database, and user are required — no pg-side defaults.
+*/
+function buildWorkerDbConfig(postgresUrl, options) {
+	let parsed;
+	try {
+		parsed = new URL(postgresUrl);
+	} catch {
+		throw new Error(`Worker pool requires a valid postgres:// URL for the reactor database, got "${postgresUrl}"`);
+	}
+	const database = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
+	if (!parsed.hostname || !database) throw new Error(`Worker pool requires a postgres URL with a host and database name, got "${postgresUrl}"`);
+	if (!parsed.username) throw new Error(`Worker pool requires explicit credentials in the postgres URL (workers open their own connections), got "${postgresUrl}"`);
+	const sslmode = parsed.searchParams.get("sslmode");
+	const ssl = parsed.searchParams.get("ssl") === "true" || sslmode !== null && sslmode !== "disable";
+	return {
+		host: parsed.hostname,
+		port: parsed.port ? Number(parsed.port) : 5432,
+		database,
+		user: decodeURIComponent(parsed.username),
+		password: decodeURIComponent(parsed.password),
+		ssl,
+		applicationName: "switchboard-worker",
+		poolSize: options.dbPoolSizePerWorker,
+		connectionTimeoutMillis: options.acquireTimeoutMs
+	};
+}
+/** Specifiers of the base models switchboard always registers. */
+const BASE_MODEL_SPECIFIERS = [
+	"document-model",
+	"@powerhousedao/shared/document-drive",
+	"@powerhousedao/reactor-drive"
+];
+/**
+* Resolves base models and configured package identifiers to `{ filePath }`
+* sources for the reactor builder. Resolution to absolute paths happens here
+* because workers (and the builder) resolve bare specifiers from the reactor
+* package's own dependency context, which cannot see switchboard or project
+* packages. Unresolvable identifiers are skipped with a warning; the builder
+* fails the boot if a registered model ends up without an importable source.
+*/
+async function resolveWorkerModelSources(packages, logger) {
+	const sources = [];
+	for (const identifier of [...BASE_MODEL_SPECIFIERS, ...packages]) {
+		const filePath = await resolveModelModuleFile(identifier);
+		if (!filePath) {
+			logger.warn(`Worker model sources: no importable document-models entry for "${identifier}", skipping`);
+			continue;
+		}
+		sources.push({ filePath });
+	}
+	return sources;
+}
+/**
+* Absolute file path of a source's models barrel. Mirrors reactor-api's
+* import-resolver: import.meta.resolve, then the project's node_modules via
+* the package.json exports map / dist layout.
+*/
+async function resolveModelModuleFile(source) {
+	if (isFsPath(source)) return resolveFromPackageDir(source, "./document-models");
+	const specifier = BASE_MODEL_SPECIFIERS.includes(source) ? source : `${source}/document-models`;
+	try {
+		const resolved = import.meta.resolve(specifier);
+		if (resolved.startsWith("file:")) return fileURLToPath(resolved);
+	} catch {}
+	const { packageName, subpath } = splitSpecifier(specifier);
+	const packageDir = path.join(process.cwd(), "node_modules", packageName);
+	if (!existsSync(packageDir)) return null;
+	let realDir;
+	try {
+		realDir = realpathSync(packageDir);
+	} catch {
+		return null;
+	}
+	return resolveFromPackageDir(realDir, subpath);
+}
+function splitSpecifier(specifier) {
+	const parts = specifier.split("/");
+	const packageSegments = specifier.startsWith("@") ? 2 : 1;
+	const packageName = parts.slice(0, packageSegments).join("/");
+	const rest = parts.slice(packageSegments).join("/");
+	return {
+		packageName,
+		subpath: rest ? `./${rest}` : "."
+	};
+}
+/** Exports-map lookup (import condition), then conventional dist paths. */
+async function resolveFromPackageDir(packageDir, subpath) {
+	const fromManifest = await resolveViaManifest(packageDir, subpath);
+	if (fromManifest) return fromManifest;
+	const candidates = subpath === "." ? [path.join(packageDir, "dist", "index.js")] : [
+		path.join(packageDir, "dist", subpath.slice(2), "index.js"),
+		path.join(packageDir, "dist", `${subpath.slice(2)}.js`),
+		path.join(packageDir, subpath.slice(2), "index.js")
+	];
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+	return null;
+}
+async function resolveViaManifest(packageDir, subpath) {
+	let raw;
+	try {
+		raw = await readFile(path.join(packageDir, "package.json"), "utf8");
+	} catch {
+		return null;
+	}
+	let manifest;
+	try {
+		manifest = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	let entry;
+	const exportsField = manifest.exports;
+	if (exportsField !== null && typeof exportsField === "object" && !Array.isArray(exportsField)) {
+		const map = exportsField;
+		entry = Object.keys(map).some((key) => key.startsWith(".")) ? map[subpath] : subpath === "." ? map : void 0;
+	} else if (typeof exportsField === "string" && subpath === ".") entry = exportsField;
+	let target = pickImportTarget(entry);
+	if (!target && subpath === "." && typeof manifest.main === "string") target = manifest.main;
+	if (!target) return null;
+	const resolved = path.join(packageDir, target);
+	return existsSync(resolved) ? resolved : null;
+}
+function pickImportTarget(entry) {
+	if (typeof entry === "string") return entry;
+	if (typeof entry !== "object" || entry === null) return null;
+	const conditions = entry;
+	for (const condition of [
+		"import",
+		"node",
+		"default"
+	]) {
+		const value = conditions[condition];
+		if (typeof value === "string") return value;
+	}
+	return null;
+}
+function isFsPath(identifier) {
+	return path.isAbsolute(identifier) || identifier.startsWith("./") || identifier.startsWith("../");
+}
+function parseWorkerCount(raw) {
+	if (raw === void 0 || raw.trim() === "") return;
+	if (raw.trim().toLowerCase() === "auto") return "auto";
+	const value = Number.parseInt(raw, 10);
+	if (!Number.isInteger(value) || value < 0 || String(value) !== raw.trim()) throw new Error(`REACTOR_WORKERS must be "auto" or a non-negative integer, got "${raw}"`);
+	return value;
+}
+function parseNonNegativeInt(raw, name) {
+	if (raw === void 0 || raw.trim() === "") return;
+	const value = Number.parseInt(raw, 10);
+	if (!Number.isInteger(value) || value < 0 || String(value) !== raw.trim()) throw new Error(`${name} must be a non-negative integer, got "${raw}"`);
+	return value;
+}
+//#endregion
 //#region src/feature-flags.ts
 async function initFeatureFlags() {
 	const provider = new EnvVarProvider();
@@ -697,6 +1084,15 @@ async function initServer(serverPort, options, renown) {
 	}
 	const reactorPgliteMajor = reactorPgliteDir ? resolvePgliteMajorForDir(reactorPgliteDir) : null;
 	const readModelPgliteMajor = readModelPgliteDir ? resolvePgliteMajorForDir(readModelPgliteDir) : null;
+	let workerPool = resolveWorkerPoolOptions(options.workerPool, process.env);
+	if (workerPool && options.reactor) {
+		logger.warn("Worker pool configuration ignored: the caller-provided reactor owns its own executor");
+		workerPool = null;
+	}
+	if (workerPool) {
+		if (dev) throw new Error("The executor worker pool (REACTOR_WORKERS) is not supported in dev mode: Vite-loaded document models cannot cross a worker-thread boundary");
+		if (!reactorDbUrl || !isPostgresUrl(reactorDbUrl)) throw new Error("The executor worker pool (REACTOR_WORKERS) requires a Postgres reactor database — set PH_REACTOR_DATABASE_URL or PH_SWITCHBOARD_DATABASE_URL. PGlite cannot be shared across worker threads.");
+	}
 	const apiRef = { current: void 0 };
 	let driveNodeView;
 	const config = getConfig(options.configFile ?? path$1.join(process.cwd(), "powerhouse.config.json"));
@@ -713,13 +1109,17 @@ async function initServer(serverPort, options, renown) {
 		});
 	}
 	const reactorLogger = logger.child(["reactor"]);
-	const initializeClient = async (documentModels) => {
+	const initializeClient = async (documentModels, { attachmentReferenceWriter }) => {
 		if (options.reactor) {
+			const attachmentReferenceProjection = await registerAttachmentReferenceReadModelOnModule(options.reactor, attachmentReferenceWriter);
 			if (options.reactor.reactorModule) {
 				new ReactorInstrumentation(options.reactor.reactorModule).start();
 				reactorLogger.info("Reactor metrics instrumentation started (using caller-provided reactor)");
 			}
-			return { module: options.reactor };
+			return {
+				module: options.reactor,
+				attachmentReferenceProjection
+			};
 		}
 		const baseKysely = await createReactorKysely({
 			reactorDbUrl,
@@ -732,6 +1132,7 @@ async function initServer(serverPort, options, renown) {
 		const maxSkipThreshold = parseInt(process.env.MAX_SKIP_THRESHOLD ?? "", 10);
 		const hasSkipThreshold = !isNaN(maxSkipThreshold) && maxSkipThreshold > 0;
 		if (hasSkipThreshold) logger.info(`Reactor maxSkipThreshold set to ${maxSkipThreshold}`);
+		if (hasSkipThreshold && workerPool) logger.warn("MAX_SKIP_THRESHOLD is not forwarded to executor workers and has no effect in worker-pool mode");
 		const reactorBuilder = new ReactorBuilder().withEventBus(new EventBus()).withKysely(baseKysely);
 		const clientBuilder = new ReactorClientBuilder().withReactorBuilder(reactorBuilder);
 		const vetraDocumentModels = dev ? Object.values(await import("@powerhousedao/vetra/document-models")).filter((m) => typeof m === "object" && m !== null && "documentModel" in m && "reducer" in m) : [];
@@ -742,11 +1143,24 @@ async function initServer(serverPort, options, renown) {
 			logger: reactorLogger,
 			signer: renown ? getRenownSignerConfig(renown, options.identity?.requireSignatures) : void 0
 		});
+		if (workerPool) {
+			if (!reactorDbUrl) throw new Error("unreachable: worker pool enabled without a reactor database URL");
+			const workerSources = await resolveWorkerModelSources(packages, reactorLogger);
+			reactorBuilder.withDocumentModelSources(workerSources).withWorkerPool({
+				numWorkers: workerPool.numWorkers,
+				db: buildWorkerDbConfig(reactorDbUrl, workerPool)
+			});
+			reactorLogger.info(`Executor worker pool enabled: ${workerPool.numWorkers} worker threads${workerPool.mode === "auto" ? " (auto-sized from cores)" : ""}`);
+		}
 		reactorBuilder.withReadModelFactory(async ({ operationIndex, writeCache, processorManagerConsistencyTracker }) => {
 			const nodeProcessor = new NodeProcessor(baseKysely, REACTOR_SCHEMA, operationIndex, writeCache, processorManagerConsistencyTracker);
 			await nodeProcessor.init();
 			return nodeProcessor;
 		});
+		registerAttachmentReferenceReadModel(reactorBuilder, {
+			baseKysely,
+			attachmentReferenceWriter
+		});
 		reactorBuilder.withShutdownHook(async () => {
 			if (apiRef.current) await apiRef.current.dispose();
 		});
@@ -761,7 +1175,8 @@ async function initServer(serverPort, options, renown) {
 			reactorDriveClient: new ReactorDriveClient({
 				reactor: module.client,
 				readModel: driveNodeView
-			})
+			}),
+			attachmentReferenceProjection: { status: "available" }
 		};
 	};
 	let defaultDriveUrl = void 0;
@@ -892,6 +1307,7 @@ async function initServer(serverPort, options, renown) {
 		api,
 		reactor: client,
 		attachmentService,
+		attachmentReferenceProjection: api.attachmentReferenceProjection,
 		renown,
 		port: serverPort,
 		shutdown: () => api.dispose()
@@ -949,5 +1365,5 @@ if (import.meta.main) await startSwitchboard();
 //#endregion
 export { parseForcePgVersion as a, applySwitchboardReactorDefaults as i, isPortAvailable as n, startSwitchboard as r, deriveAttachmentServiceConfig as t };
 
-//# sourceMappingURL=server-DgBz3TJW.mjs.map
-//# debugId=8a8055ab-2ceb-59fe-9007-f1d1fde8a019
+//# sourceMappingURL=server-ChK0GLG8.mjs.map
+//# debugId=b1867ed0-059f-587c-9a5f-677da3666de7