@happyvertical/smrt-app-runtime 0.43.9 → 0.44.0

package/dist/index.js

@@ -6,11 +6,826 @@ import { isAbsolute, parse, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { Worker } from "node:worker_threads";
 import { resolveApplicationRuntime } from "@happyvertical/smrt-config";
-import { TaskRunner } from "@happyvertical/smrt-jobs";
+import { ScheduleRunner, TaskRunner } from "@happyvertical/smrt-jobs";
 import { Person, ProfileTypeCollection } from "@happyvertical/smrt-profiles";
 import { withSystemContext } from "@happyvertical/smrt-tenancy";
 import { DEFAULT_ROLE_SLUGS, MembershipCollection, MembershipStatus, RoleCollection, SessionCollection, SessionService, TenantService, UserCollection, UserStatus } from "@happyvertical/smrt-users";
 import { getDatabase } from "@happyvertical/sql";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/deployed-runtime.ts
+var DeployedRuntimeError = class extends Error {
+	constructor(code, message, component) {
+		super(message);
+		this.code = code;
+		this.component = component;
+		this.name = "DeployedRuntimeError";
+	}
+	code;
+	component;
+};
+var DeployedRuntimeCleanupError = class extends DeployedRuntimeError {
+	constructor(cleanup) {
+		super("provider_unavailable", "The database connection could not be closed after startup failed; retry cleanup and inspect the provider's private logs.", "database");
+		this.cleanup = cleanup;
+		this.name = "DeployedRuntimeCleanupError";
+	}
+	cleanup;
+	cleaned = false;
+	cleanupAttempt;
+	async retryCleanup() {
+		if (this.cleaned) return;
+		if (!this.cleanupAttempt) this.cleanupAttempt = Promise.resolve().then(() => this.cleanup()).then(() => {
+			this.cleaned = true;
+		}).catch(() => {
+			throw this;
+		}).finally(() => {
+			this.cleanupAttempt = void 0;
+		});
+		return this.cleanupAttempt;
+	}
+};
+async function initializeDeployedApplicationRuntime(options) {
+	const resolvedRuntime = resolveDeployedRuntime(options);
+	const bindings = validateBindings(options, resolvedRuntime);
+	const prepareDatabase = snapshotPrepareDatabase(options);
+	await checkProvider("authentication", () => bindings.authentication.readiness());
+	await checkProvider("assets", () => bindings.assets.readiness());
+	await checkProvider("secrets", () => bindings.secrets.readiness());
+	let db;
+	try {
+		db = await bindings.database.connect();
+	} catch {
+		throw unavailable("database");
+	}
+	let validDatabase = false;
+	try {
+		validDatabase = isDatabaseInterface(db);
+	} catch {}
+	if (!validDatabase) await cleanupAfterStartupFailure(bindings.database, db, new DeployedRuntimeError("invalid_configuration", "The database adapter did not return a valid database connection.", "database"));
+	try {
+		await checkDatabase(bindings.database, db);
+	} catch (error) {
+		await cleanupAfterStartupFailure(bindings.database, db, error);
+	}
+	try {
+		await prepareDatabase?.(db);
+	} catch {
+		await cleanupAfterStartupFailure(bindings.database, db, new DeployedRuntimeError("provider_unavailable", "The PostgreSQL migration step failed; inspect the application migration logs.", "database"));
+	}
+	return new InitializedDeployedApplicationRuntime(db, resolvedRuntime, bindings);
+}
+function resolveDeployedRuntime(options) {
+	let plainOptions = false;
+	try {
+		plainOptions = isPlainRecord(options);
+	} catch {}
+	if (!plainOptions) throw new DeployedRuntimeError("invalid_configuration", "Deployed runtime options must be an object.");
+	let profile;
+	let providers;
+	try {
+		profile = options.profile;
+		providers = options.providers;
+	} catch {
+		throw new DeployedRuntimeError("invalid_configuration", "Deployed runtime options could not be read safely.");
+	}
+	if (profile !== "self-hosted" && profile !== "cloud") throw new DeployedRuntimeError("invalid_configuration", "Deployed runtime initialization requires the self-hosted or cloud profile.");
+	try {
+		return resolveApplicationRuntime({
+			profile,
+			providers
+		});
+	} catch {
+		throw new DeployedRuntimeError("invalid_configuration", "Deployed runtime provider options could not be read safely.");
+	}
+}
+function validateBindings(options, runtime) {
+	const database = requireObjectBinding(readBindingOption(options, "database", "database"), "database");
+	let engine;
+	let connect;
+	let readiness;
+	let close;
+	try {
+		engine = database.engine;
+		connect = database.connect;
+		readiness = database.readiness;
+		close = database.close;
+	} catch {
+		throw invalidBinding("database");
+	}
+	requireFunction(connect, "database", "connect");
+	requireOptionalFunction(readiness, "database", "readiness");
+	requireFunction(close, "database", "close");
+	if (engine !== runtime.providers.database.engine) throw mismatch("database", runtime.providers.database.engine);
+	return {
+		database: Object.freeze({
+			engine,
+			connect: bindCallback(connect, database, "database"),
+			readiness: typeof readiness === "function" ? bindCallback(readiness, database, "database") : void 0,
+			close: bindCallback(close, database, "database")
+		}),
+		authentication: requireProviderBinding(readBindingOption(options, "authentication", "authentication"), "authentication", runtime.providers.authentication.provider),
+		assets: requireProviderBinding(readBindingOption(options, "assets", "assets"), "assets", runtime.providers.assets.provider),
+		secrets: requireProviderBinding(readBindingOption(options, "secrets", "secrets"), "secrets", runtime.providers.secrets.provider)
+	};
+}
+function snapshotPrepareDatabase(options) {
+	let prepareDatabase;
+	try {
+		prepareDatabase = options.prepareDatabase;
+	} catch {
+		throw invalidBinding("database");
+	}
+	requireOptionalFunction(prepareDatabase, "database", "prepareDatabase");
+	return typeof prepareDatabase === "function" ? bindCallback(prepareDatabase, options, "database") : void 0;
+}
+function readBindingOption(options, field, component) {
+	try {
+		return options[field];
+	} catch {
+		throw invalidBinding(component);
+	}
+}
+function requireProviderBinding(value, component, expectedProvider) {
+	const binding = requireObjectBinding(value, component);
+	let provider;
+	let readiness;
+	try {
+		provider = binding.provider;
+		readiness = binding.readiness;
+	} catch {
+		throw invalidBinding(component);
+	}
+	if (provider !== expectedProvider) throw mismatch(component, expectedProvider);
+	requireFunction(readiness, component, "readiness");
+	return Object.freeze({
+		provider,
+		readiness: bindCallback(readiness, binding, component)
+	});
+}
+function requireObjectBinding(value, component) {
+	let valid = false;
+	try {
+		valid = typeof value === "object" && value !== null && !Array.isArray(value);
+	} catch {}
+	if (!valid) throw new DeployedRuntimeError("invalid_configuration", `The ${component} provider binding is required.`, component);
+	return value;
+}
+function invalidBinding(component) {
+	return new DeployedRuntimeError("invalid_configuration", `The ${component} provider binding could not be read safely.`, component);
+}
+function bindCallback(callback, receiver, component) {
+	try {
+		return Reflect.apply(Function.prototype.bind, callback, [receiver]);
+	} catch {
+		throw invalidBinding(component);
+	}
+}
+function requireFunction(value, component, field) {
+	if (typeof value !== "function") throw new DeployedRuntimeError("invalid_configuration", `The ${component} provider requires a ${field} callback.`, component);
+}
+function requireOptionalFunction(value, component, field) {
+	if (value !== void 0) requireFunction(value, component, field);
+}
+function mismatch(component, expectedProvider) {
+	return new DeployedRuntimeError("provider_mismatch", `The ${component} binding does not match the selected ${expectedProvider} provider.`, component);
+}
+function unavailable(component) {
+	return new DeployedRuntimeError("provider_unavailable", `The ${component} provider is not ready; inspect that provider's private logs.`, component);
+}
+async function checkProvider(component, check) {
+	try {
+		await check();
+	} catch {
+		throw unavailable(component);
+	}
+}
+async function checkDatabase(binding, db) {
+	try {
+		await binding.readiness?.(db);
+		if (!isValidPostgresProbe(await db.query("SELECT current_setting('server_version_num') AS smrt_postgres_version"))) throw new Error("invalid probe");
+	} catch {
+		throw unavailable("database");
+	}
+}
+var InitializedDeployedApplicationRuntime = class {
+	constructor(db, resolvedRuntime, bindings) {
+		this.db = db;
+		this.resolvedRuntime = resolvedRuntime;
+		this.bindings = bindings;
+		this.snapshot = createDiagnostics(resolvedRuntime);
+		this.sessionService = new SessionService({ db });
+	}
+	db;
+	resolvedRuntime;
+	bindings;
+	state = "running";
+	closeAttempt;
+	pendingReadinessChecks = /* @__PURE__ */ new Set();
+	pendingSessionRestorations = /* @__PURE__ */ new Set();
+	pendingWorkerInitializations = /* @__PURE__ */ new Set();
+	pendingWorkerOperations = /* @__PURE__ */ new Set();
+	lifecycleOperationContext = new AsyncLocalStorage();
+	activeLifecycleOperations = /* @__PURE__ */ new Set();
+	workerCleanups = /* @__PURE__ */ new Set();
+	sessionService;
+	sessionServiceReady;
+	snapshot;
+	async restoreSession(sessionId) {
+		this.assertRunning();
+		const operation = this.beginLifecycleOperation(() => this.restoreSessionWhileRunning(sessionId));
+		this.pendingSessionRestorations.add(operation);
+		try {
+			return await operation;
+		} finally {
+			this.pendingSessionRestorations.delete(operation);
+		}
+	}
+	async restoreSessionWhileRunning(sessionId) {
+		let context;
+		try {
+			await this.initializeSessionService();
+			context = await this.sessionService.loadSessionContext(sessionId);
+		} catch {
+			throw unavailable("authentication");
+		}
+		this.assertRunning();
+		if (context && this.resolvedRuntime.providers.tenancy.context === "required") {
+			let tenantId;
+			try {
+				tenantId = context.tenantId;
+			} catch {
+				throw unavailable("authentication");
+			}
+			if (typeof tenantId !== "string" || tenantId.trim().length === 0) throw new DeployedRuntimeError("tenant_context_required", "The authenticated session does not include the required tenant context.", "authentication");
+			let tenantAuthorized = false;
+			try {
+				const membership = context.membership;
+				const authorization = context.tenantAuthorization;
+				const membershipId = authorization?.membershipId;
+				const validMembershipId = typeof membershipId === "string" && membershipId.trim().length > 0;
+				if (membership?.isActive() === true) tenantAuthorized = validMembershipId && membership.id === membershipId && authorization?.inheritedFromTenantId === null;
+				else if (membership === null) tenantAuthorized = validMembershipId && typeof authorization?.inheritedFromTenantId === "string" && authorization.inheritedFromTenantId.trim().length > 0;
+			} catch {
+				throw unavailable("authentication");
+			}
+			if (!tenantAuthorized) throw new DeployedRuntimeError("tenant_context_unauthorized", "The authenticated session is not authorized for its tenant context.", "authentication");
+		}
+		return context;
+	}
+	async createTaskWorker(config = {}) {
+		this.assertRunning();
+		const operation = this.beginLifecycleOperation(() => this.initializeTaskWorker(config));
+		this.pendingWorkerInitializations.add(operation);
+		try {
+			const runner = await operation;
+			return this.retainWorker(runner);
+		} finally {
+			this.pendingWorkerInitializations.delete(operation);
+		}
+	}
+	async createScheduleWorker(config = {}) {
+		this.assertRunning();
+		const operation = this.beginLifecycleOperation(() => this.initializeScheduleWorker(config));
+		this.pendingWorkerInitializations.add(operation);
+		try {
+			const runner = await operation;
+			return this.retainWorker(runner);
+		} finally {
+			this.pendingWorkerInitializations.delete(operation);
+		}
+	}
+	diagnostics() {
+		return this.snapshot;
+	}
+	health() {
+		return Object.freeze({
+			schemaVersion: 1,
+			profile: this.resolvedRuntime.profile,
+			status: this.state === "running" ? "healthy" : "stopped"
+		});
+	}
+	async readiness() {
+		if (this.state !== "running") return createStoppedReadiness(this.resolvedRuntime.profile);
+		const operation = this.beginLifecycleOperation(() => this.checkReadinessWhileRunning());
+		this.pendingReadinessChecks.add(operation);
+		try {
+			return await operation;
+		} finally {
+			this.pendingReadinessChecks.delete(operation);
+		}
+	}
+	async checkReadinessWhileRunning() {
+		const results = await Promise.all([
+			probe(() => checkDatabase(this.bindings.database, this.db)),
+			probe(() => this.bindings.authentication.readiness()),
+			probe(() => this.bindings.assets.readiness()),
+			probe(() => this.bindings.secrets.readiness())
+		]);
+		if (this.state !== "running") return createStoppedReadiness(this.resolvedRuntime.profile);
+		const [database, authentication, assets, secrets] = results;
+		return freezeReadiness(this.resolvedRuntime.profile, {
+			database,
+			authentication,
+			assets,
+			secrets
+		}, results.every((result) => result.status === "ready"));
+	}
+	async close() {
+		const operationToken = this.lifecycleOperationContext.getStore();
+		const requestedFromLifecycleOperation = operationToken !== void 0 && this.activeLifecycleOperations.has(operationToken);
+		if (this.state === "stopped") return;
+		if (this.closeAttempt) {
+			if (requestedFromLifecycleOperation) return;
+			return this.closeAttempt;
+		}
+		this.state = "closing";
+		const pendingOperations = [
+			...this.pendingReadinessChecks,
+			...this.pendingSessionRestorations,
+			...this.pendingWorkerInitializations,
+			...this.pendingWorkerOperations
+		];
+		const shutdownToken = /* @__PURE__ */ Symbol("deployed-runtime-shutdown");
+		this.activeLifecycleOperations.add(shutdownToken);
+		const attempt = Promise.resolve().then(() => this.lifecycleOperationContext.run(shutdownToken, async () => {
+			await Promise.allSettled(pendingOperations);
+			await this.cleanupWorkers();
+			await this.closeConnection();
+		})).finally(() => {
+			this.activeLifecycleOperations.delete(shutdownToken);
+		});
+		this.closeAttempt = attempt.finally(() => {
+			this.closeAttempt = void 0;
+		});
+		if (requestedFromLifecycleOperation) {
+			this.closeAttempt.catch(() => void 0);
+			return;
+		}
+		return this.closeAttempt;
+	}
+	async initializeTaskWorker(config) {
+		let runner;
+		try {
+			runner = new TaskRunner(config);
+			await runner.initialize(this.db);
+		} catch {
+			if (runner) await this.stopOrRetainUnreturnedWorker(runner);
+			throw unavailable("database");
+		}
+		if (this.state !== "running") {
+			await this.stopOrRetainUnreturnedWorker(runner);
+			this.assertRunning();
+		}
+		return runner;
+	}
+	async initializeScheduleWorker(config) {
+		let runner;
+		try {
+			runner = new ScheduleRunner(config);
+			await runner.initialize(this.db);
+		} catch {
+			if (runner) await this.stopOrRetainUnreturnedWorker(runner);
+			throw unavailable("database");
+		}
+		if (this.state !== "running") {
+			await this.stopOrRetainUnreturnedWorker(runner);
+			this.assertRunning();
+		}
+		return runner;
+	}
+	async stopOrRetainUnreturnedWorker(runner) {
+		const cleanup = () => runner.stop();
+		try {
+			await cleanup();
+		} catch {
+			this.workerCleanups.add(cleanup);
+		}
+	}
+	retainWorker(runner) {
+		const start = runner.start.bind(runner);
+		const stop = runner.stop.bind(runner);
+		let operationTail = Promise.resolve();
+		const queueOperation = (callback) => {
+			const previous = operationTail;
+			const operation = this.beginLifecycleOperation(async () => {
+				await previous;
+				await callback();
+			});
+			operationTail = operation.catch(() => void 0);
+			this.pendingWorkerOperations.add(operation);
+			operation.then(() => {
+				this.pendingWorkerOperations.delete(operation);
+			}, () => {
+				this.pendingWorkerOperations.delete(operation);
+			});
+			return operation;
+		};
+		const ownedStart = async () => {
+			this.assertRunning();
+			return queueOperation(async () => {
+				this.assertRunning();
+				try {
+					await start();
+					this.assertRunning();
+				} catch {
+					if (this.state === "running") try {
+						await stop();
+					} catch {}
+					if (this.state !== "running") this.assertRunning();
+					throw unavailable("database");
+				}
+			});
+		};
+		const ownedStop = () => queueOperation(async () => {
+			try {
+				await stop();
+			} catch {
+				throw unavailable("database");
+			}
+		});
+		Object.defineProperties(runner, {
+			start: {
+				configurable: false,
+				enumerable: false,
+				value: ownedStart,
+				writable: false
+			},
+			stop: {
+				configurable: false,
+				enumerable: false,
+				value: ownedStop,
+				writable: false
+			}
+		});
+		this.workerCleanups.add(ownedStop);
+		return runner;
+	}
+	async cleanupWorkers() {
+		const cleanups = [...this.workerCleanups];
+		const results = await Promise.allSettled(cleanups.map((cleanup) => Promise.resolve().then(cleanup)));
+		let cleanupFailed = false;
+		for (const [index, result] of results.entries()) if (result.status === "fulfilled") {
+			const cleanup = cleanups[index];
+			if (cleanup) this.workerCleanups.delete(cleanup);
+		} else cleanupFailed = true;
+		if (cleanupFailed) {
+			this.state = "close-failed";
+			throw unavailable("database");
+		}
+	}
+	initializeSessionService() {
+		if (!this.sessionServiceReady) this.sessionServiceReady = this.sessionService.initialize().catch((error) => {
+			this.sessionServiceReady = void 0;
+			throw error;
+		});
+		return this.sessionServiceReady;
+	}
+	beginLifecycleOperation(operation) {
+		const token = /* @__PURE__ */ Symbol("deployed-runtime-operation");
+		this.activeLifecycleOperations.add(token);
+		return Promise.resolve().then(() => this.lifecycleOperationContext.run(token, operation)).finally(() => {
+			this.activeLifecycleOperations.delete(token);
+		});
+	}
+	async closeConnection() {
+		try {
+			await this.bindings.database.close(this.db);
+			this.state = "stopped";
+		} catch {
+			this.state = "close-failed";
+			throw new DeployedRuntimeError("provider_unavailable", "The database connection could not be closed; inspect the provider's private logs.", "database");
+		}
+	}
+	assertRunning() {
+		if (this.state !== "running") throw new DeployedRuntimeError("runtime_stopped", "The deployed application runtime has already stopped.");
+	}
+};
+function createDiagnostics(runtime) {
+	const provider = (value) => Object.freeze({
+		provider: value,
+		configured: true
+	});
+	return deepFreeze$1({
+		schemaVersion: 1,
+		runtime,
+		providers: {
+			database: provider(runtime.providers.database.engine),
+			authentication: provider(runtime.providers.authentication.provider),
+			assets: provider(runtime.providers.assets.provider),
+			secrets: provider(runtime.providers.secrets.provider)
+		},
+		tenancy: {
+			mode: runtime.providers.tenancy.mode,
+			context: runtime.providers.tenancy.context,
+			isolation: runtime.providers.tenancy.isolation,
+			rootTenantFallback: "disabled"
+		},
+		workers: {
+			topology: runtime.providers.jobs.topology,
+			taskProcess: "separate",
+			scheduleProcess: "separate",
+			replicas: runtime.providers.jobs.topology === "scalable" ? "horizontal" : "operator-managed"
+		},
+		secretValuesIncluded: false
+	});
+}
+async function probe(check) {
+	try {
+		await check();
+		return Object.freeze({ status: "ready" });
+	} catch {
+		return Object.freeze({ status: "not-ready" });
+	}
+}
+function createStoppedReadiness(profile) {
+	const stopped = Object.freeze({ status: "not-ready" });
+	return freezeReadiness(profile, {
+		database: stopped,
+		authentication: stopped,
+		assets: stopped,
+		secrets: stopped
+	}, false);
+}
+function freezeReadiness(profile, components, ready) {
+	return deepFreeze$1({
+		schemaVersion: 1,
+		profile,
+		status: ready ? "ready" : "not-ready",
+		components,
+		secretValuesIncluded: false
+	});
+}
+function isPlainRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isDatabaseInterface(value) {
+	return typeof value === "object" && value !== null && typeof value.query === "function";
+}
+function isValidPostgresProbe(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const rows = value.rows;
+	if (!Array.isArray(rows) || rows.length !== 1) return false;
+	const row = rows[0];
+	if (typeof row !== "object" || row === null) return false;
+	const version = row.smrt_postgres_version;
+	return typeof version === "string" && /^\d+$/.test(version);
+}
+async function cleanupAfterStartupFailure(binding, db, startupError) {
+	const cleanup = () => binding.close(db);
+	try {
+		await cleanup();
+	} catch {
+		throw new DeployedRuntimeCleanupError(cleanup);
+	}
+	throw startupError;
+}
+function deepFreeze$1(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value && typeof value === "object") {
+		if (seen.has(value)) return value;
+		seen.add(value);
+		if (!Object.isFrozen(value)) Object.freeze(value);
+		for (const child of Object.values(value)) deepFreeze$1(child, seen);
+	}
+	return value;
+}
+//#endregion
+//#region src/runtime-diagnostics.ts
+var RUNTIME_DIAGNOSTICS_SCHEMA_VERSION = 1;
+var MAX_RUNTIME_DIAGNOSTIC_TOOLS = 64;
+var MAX_RUNTIME_DIAGNOSTIC_ERRORS = 8;
+var RUNTIME_WORKER_FRESHNESS_SECONDS = 120;
+var CAPABILITY_IDS = [
+	"asset-storage",
+	"authentication",
+	"background-jobs",
+	"database",
+	"paid-capabilities",
+	"secret-storage"
+];
+var ERROR_CODES = [
+	"authentication_unavailable",
+	"database_unavailable",
+	"migration_required",
+	"provider_unavailable",
+	"runtime_stopped",
+	"worker_stale"
+];
+var PROHIBITED_IDENTIFIER_PARTS = /* @__PURE__ */ new Set([
+	"authorization",
+	"cookie",
+	"constructor",
+	"credential",
+	"email",
+	"hash",
+	"key",
+	"log",
+	"logs",
+	"password",
+	"path",
+	"record",
+	"prototype",
+	"secret",
+	"session",
+	"stack",
+	"tenant",
+	"token",
+	"url",
+	"user"
+]);
+function projectRuntimeDiagnostics(input) {
+	const source = plainRecord(input);
+	const observedAtValue = read(source, "observedAt");
+	const observedAtMilliseconds = timestampMilliseconds(observedAtValue);
+	const observedAt = coarseTimestamp(observedAtValue) ?? EPOCH;
+	const profile = runtimeProfile(read(source, "profile"));
+	const worker = projectWorker(read(source, "worker"), observedAt, observedAtMilliseconds);
+	const capabilities = projectCapabilities(read(source, "capabilities"));
+	const tools = canonicalTools(read(source, "toolNames"));
+	return deepFreeze({
+		schemaVersion: 1,
+		profile,
+		health: oneOf(read(source, "health"), HEALTH_VALUES, "unknown"),
+		schema: projectSchema(read(source, "schema")),
+		capabilities,
+		tools: {
+			names: tools,
+			count: tools.length,
+			digest: createHash("sha256").update(tools.join("\n")).digest("hex")
+		},
+		operationalDifferences: {
+			backgroundJobs: capabilityStatus(capabilities, "background-jobs") === "available" ? "enabled" : "disabled",
+			workerTopology: worker.topology
+		},
+		worker,
+		recentErrors: projectErrors(read(source, "recentErrors"))
+	});
+}
+var EPOCH = "1970-01-01T00:00:00.000Z";
+var PROFILES = [
+	"local",
+	"self-hosted",
+	"cloud",
+	"unknown"
+];
+var HEALTH_VALUES = [
+	"healthy",
+	"degraded",
+	"stopped",
+	"unknown"
+];
+var SCHEMA_VALUES = [
+	"ready",
+	"not-ready",
+	"unknown"
+];
+var MIGRATION_VALUES = [
+	"current",
+	"failed",
+	"pending",
+	"unknown"
+];
+var CAPABILITY_VALUES = [
+	"available",
+	"disabled",
+	"unavailable",
+	"unknown"
+];
+var WORKER_TOPOLOGIES = [
+	"embedded",
+	"external",
+	"inline",
+	"scalable"
+];
+function runtimeProfile(value) {
+	return oneOf(value, PROFILES, "unknown");
+}
+function projectSchema(value) {
+	const source = plainRecord(value);
+	return {
+		status: oneOf(read(source, "status"), SCHEMA_VALUES, "unknown"),
+		migrations: oneOf(read(source, "migrations"), MIGRATION_VALUES, "unknown")
+	};
+}
+function projectCapabilities(value) {
+	const source = plainRecord(value);
+	return CAPABILITY_IDS.map((id) => ({
+		id,
+		status: oneOf(read(source, id), CAPABILITY_VALUES, "unknown")
+	}));
+}
+function canonicalTools(value) {
+	const names = /* @__PURE__ */ new Set();
+	for (const candidate of safeArrayItems(value, 256)) {
+		if (typeof candidate !== "string" || !isPublicIdentifier(candidate)) continue;
+		names.add(candidate);
+	}
+	return [...names].sort().slice(0, 64);
+}
+function isPublicIdentifier(value) {
+	if (value.length < 1 || value.length > 80 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value)) return false;
+	return !value.split(/[._-]/).some((part) => PROHIBITED_IDENTIFIER_PARTS.has(part));
+}
+function projectWorker(value, observedAt, observedAtMilliseconds) {
+	const source = plainRecord(value);
+	const topology = oneOf(read(source, "topology"), WORKER_TOPOLOGIES, "inline");
+	const required = read(source, "required") === true;
+	const heartbeatValue = read(source, "heartbeatAt");
+	const heartbeatMilliseconds = timestampMilliseconds(heartbeatValue);
+	const heartbeatAt = coarseTimestamp(heartbeatValue);
+	let liveness = "not-required";
+	if (required) {
+		liveness = "unknown";
+		if (heartbeatMilliseconds !== null && observedAtMilliseconds !== null) {
+			const ageSeconds = (observedAtMilliseconds - heartbeatMilliseconds) / 1e3;
+			if (ageSeconds >= 0) liveness = ageSeconds <= 120 ? "alive" : "stale";
+		}
+	}
+	return {
+		topology,
+		liveness,
+		heartbeatAt,
+		observedAt
+	};
+}
+function projectErrors(value) {
+	const errors = [];
+	for (const candidate of safeArrayItems(value, 32)) {
+		const source = plainRecord(candidate);
+		const at = coarseTimestamp(read(source, "at"));
+		if (!at) continue;
+		const rawCode = read(source, "code");
+		const code = ERROR_CODES.includes(rawCode) ? rawCode : "runtime_error";
+		errors.push({
+			code,
+			at
+		});
+	}
+	return errors.sort((left, right) => left.at === right.at ? left.code.localeCompare(right.code) : right.at.localeCompare(left.at)).slice(0, 8);
+}
+function capabilityStatus(capabilities, id) {
+	return capabilities.find((capability) => capability.id === id)?.status ?? "unknown";
+}
+function coarseTimestamp(value) {
+	const milliseconds = timestampMilliseconds(value);
+	if (milliseconds === null) return null;
+	const minute = Math.floor(milliseconds / 6e4) * 6e4;
+	return new Date(minute).toISOString();
+}
+function timestampMilliseconds(value) {
+	try {
+		if (!(typeof value === "string" || value instanceof Date)) return null;
+		const milliseconds = value instanceof Date ? value.getTime() : Date.parse(value);
+		return Number.isFinite(milliseconds) ? milliseconds : null;
+	} catch {
+		return null;
+	}
+}
+function oneOf(value, values, fallback) {
+	return typeof value === "string" && values.includes(value) ? value : fallback;
+}
+function plainRecord(value) {
+	try {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === Object.prototype || prototype === null ? value : null;
+	} catch {
+		return null;
+	}
+}
+function read(source, key) {
+	try {
+		if (!source || !Object.hasOwn(source, key)) return;
+		return source[key];
+	} catch {
+		return;
+	}
+}
+function safeArrayItems(value, maximum) {
+	try {
+		if (!Array.isArray(value)) return [];
+		const length = Math.min(value.length, maximum);
+		if (!Number.isSafeInteger(length) || length < 0) return [];
+		const items = [];
+		for (let index = 0; index < length; index += 1) try {
+			items.push(value[index]);
+		} catch {
+			items.push(void 0);
+		}
+		return items;
+	} catch {
+		return [];
+	}
+}
+function deepFreeze(value) {
+	if (value && typeof value === "object") {
+		Object.freeze(value);
+		for (const child of Object.values(value)) if (child && typeof child === "object" && !Object.isFrozen(child)) deepFreeze(child);
+	}
+	return value;
+}
+//#endregion
 //#region src/index.ts
 var DEFAULT_BIND_HOST = "127.0.0.1";
 var DEFAULT_BOOTSTRAP_TTL_SECONDS = 600;
@@ -65,6 +880,44 @@ var INITIALIZATION_LOCK_WORKER = `
   });
 `;
 var execFileAsync = promisify(execFile);
+async function prepareLocalDatabaseStorage(options) {
+	const paths = resolveLocalRuntimePaths(options);
+	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
+	const appId = validateApplicationId(options.appId);
+	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+	const initializationLock = await acquireInitializationLock(paths.root);
+	let db;
+	let failure;
+	try {
+		await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+		db = (await acquireLocalDatabase(paths, sourceRoot, appId)).db;
+		await db.close?.();
+		db = void 0;
+	} catch (error) {
+		failure = db ? await closeDatabaseAfterFailure(db, error) : error;
+		db = void 0;
+	}
+	try {
+		await initializationLock.release();
+	} catch (releaseError) {
+		failure = failure ? preservePrimaryFailure(failure, releaseError, "initializationLockReleaseError", "Local database storage preparation and initialization-lock release both failed.") : releaseError;
+	}
+	if (failure) throw failure;
+	return paths;
+}
+async function validateLocalDatabaseStorage(options) {
+	const paths = resolveLocalRuntimePaths(options);
+	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
+	const appId = validateApplicationId(options.appId);
+	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
+	const canonicalSourceRoot = await realpath(sourceRoot);
+	await validateRootMarker(resolve(paths.root, `${ROOT_MARKER_PREFIX}${appId}`), canonicalSourceRoot);
+	await validateExistingPathChain(paths.database, canonicalSourceRoot, "file");
+	const database = await lstat(paths.database);
+	const currentUid = process.getuid?.();
+	if (database.isSymbolicLink() || !database.isFile() || currentUid !== void 0 && database.uid !== currentUid || (database.mode & 511) !== 384) throw unsafeFilesystemEntry(`Local application database must be a current-user-owned mode-0600 file: ${paths.database}`);
+	return paths;
+}
 var LocalRuntimeError = class extends Error {
 	constructor(code, message) {
 		super(message);
@@ -74,7 +927,7 @@ var LocalRuntimeError = class extends Error {
 	code;
 };
 function resolveLocalRuntimePaths(options) {
-	const appId = normalizeAppId(options.appId);
+	const appId = validateApplicationId(options.appId);
 	const runtimePlatform = options.platform ?? platform();
 	const runtimeHome = options.homeDirectory ?? homedir();
 	const defaultRoot = defaultApplicationDataRoot(runtimePlatform, runtimeHome, options.env ?? process.env);
@@ -99,7 +952,7 @@ async function initializeLocalApplicationRuntime(options) {
 	});
 	const paths = resolveLocalRuntimePaths(options);
 	const sourceRoot = resolve(options.sourceRoot ?? process.cwd());
-	const appId = normalizeAppId(options.appId);
+	const appId = validateApplicationId(options.appId);
 	await preflightLocalApplicationRoot(paths.root, sourceRoot, appId);
 	const initializationLock = await acquireInitializationLock(paths.root);
 	let db;
@@ -495,13 +1348,16 @@ async function acquireLocalDatabase(paths, sourceRoot, appId) {
 				root: paths.root
 			}
 		});
+		await enforcePrivateDatabaseMode(paths.database, canonicalSourceRoot);
 	} catch (error) {
+		if (db) throw await closeDatabaseAfterFailure(db, error);
 		if (prepared.pendingMarkerCreatedByAttempt) {
 			await removeMarkerIfPresent(prepared.pendingMarker, canonicalSourceRoot);
 			await removeCreatedDirectories(createdDirectories);
 		}
 		throw error;
 	}
+	if (!db) throw new Error("Local runtime database acquisition returned no database.");
 	try {
 		await publishRootMarker(prepared.finalMarker, canonicalSourceRoot);
 		await removeMarkerIfPresent(prepared.pendingMarker, canonicalSourceRoot);
@@ -513,6 +1369,15 @@ async function acquireLocalDatabase(paths, sourceRoot, appId) {
 		db
 	};
 }
+async function enforcePrivateDatabaseMode(path, canonicalSourceRoot) {
+	const database = await openSafeFile(path, constants.O_RDWR, 384, "Local application database", canonicalSourceRoot);
+	try {
+		await database.chmod(384);
+		await database.sync();
+	} finally {
+		await database.close();
+	}
+}
 async function closeDatabaseAfterFailure(db, primaryFailure) {
 	try {
 		await db.close?.();
@@ -895,11 +1760,17 @@ function normalizeLoopbackHost(value) {
 	if (octets.length === 4 && octets.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255) && Number(octets[0]) === 127) return host;
 	throw new LocalRuntimeError("unsafe_public_exposure", "Owner bootstrap is restricted to a loopback IP literal. Use ::1 or 127.0.0.0/8.");
 }
-function normalizeAppId(value) {
+function validateApplicationId(value) {
 	const appId = value.trim().toLowerCase();
 	if (!/^[a-z0-9][a-z0-9.-]{0,62}$/.test(appId)) throw new LocalRuntimeError("invalid_configuration", "appId must contain only lowercase letters, digits, dots, or hyphens.");
 	return appId;
 }
+function encodeApplicationId(value) {
+	const source = value.trim().toLowerCase();
+	if (/^[a-z0-9][a-z0-9.-]{0,62}$/.test(source)) return source;
+	const digest = createHash("sha256").update(value.trim()).digest("hex").slice(0, 10);
+	return validateApplicationId(`${source.replace(/[^a-z0-9.-]+/g, "-").replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "").slice(0, 52).replace(/[^a-z0-9]+$/g, "") || "app"}-${digest}`);
+}
 function defaultApplicationDataRoot(runtimePlatform, runtimeHome, env) {
 	if (runtimePlatform === "darwin") return resolve(runtimeHome, "Library", "Application Support");
 	if (runtimePlatform === "win32") return resolve(env.LOCALAPPDATA ?? env.APPDATA ?? runtimeHome);
@@ -931,6 +1802,6 @@ function isDirectoryNotEmpty(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOTEMPTY";
 }
 //#endregion
-export { LocalRuntimeError, initializeLocalApplicationRuntime, resolveLocalRuntimePaths };
+export { DeployedRuntimeCleanupError, DeployedRuntimeError, LocalRuntimeError, MAX_RUNTIME_DIAGNOSTIC_ERRORS, MAX_RUNTIME_DIAGNOSTIC_TOOLS, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_WORKER_FRESHNESS_SECONDS, encodeApplicationId, initializeDeployedApplicationRuntime, initializeLocalApplicationRuntime, prepareLocalDatabaseStorage, projectRuntimeDiagnostics, resolveLocalRuntimePaths, validateApplicationId, validateLocalDatabaseStorage };
 
 //# sourceMappingURL=index.js.map