@agimon-ai/po-core 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/src/server/serverScope.d.mts

@@ -0,0 +1,123 @@
+import { PoPlatform } from "../schemas/platform.mjs";
+import { PoApiHandler, PoApiScope } from "../schemas/packageApi.mjs";
+import { PoServerPluginShare, PoServiceContract } from "../schemas/serverScope.mjs";
+import { PoServerHostService, PoServerPlugin } from "../schemas/serverPlugin.mjs";
+import { LoadedServerPackage } from "./serverPackages.mjs";
+import { Context, Events } from "@deepseek-ai/cordis";
+//#region src/server/serverScope.d.ts
+/** What a scope's owner publishes for the packages installed at its level. */
+export interface PoServerScopeHost {
+  /**
+   * The level's mount table. A host that also routes requests (`createPoServerHost` does) answers
+   * API requests for this level and every level below it that does not serve the API itself.
+   */
+  readonly host: PoServerHostService & {
+    handlerFor?(basePath: string): PoApiHandler | undefined;
+  };
+  /** Host capabilities published as `po/fs`, `po/shell`, `po/sqlite` and `po/session-storage`. */
+  readonly platform: PoPlatform;
+}
+export interface PoServerPackageSettledReport {
+  readonly packageName: string;
+  readonly durationMs: number;
+  readonly outcome: 'installed' | 'failed' | 'timed_out';
+}
+export interface PoServerInstallOptions {
+  readonly onNotice?: (message: string) => void;
+  /** Bound on each package's `apply`; defaults to `LIVE_FACTORY_TIMEOUT_MS`. */
+  readonly factoryTimeoutMs?: number;
+  /** Reports how long each package's `apply` took and how it ended, for telemetry. */
+  readonly onPackageSettled?: (report: PoServerPackageSettledReport) => void;
+}
+/**
+ * One level of the server IoC tree: its own cordis root, a parent link, the contracts bound here,
+ * and the packages installed here.
+ *
+ * Separate roots rather than one shared root, because cordis re-checks every fiber of a root on each
+ * service change; a hundred sessions in one root would make every change scan all of them. A binding
+ * is instead mirrored into each descendant root as a native service, so a plugin injects an outer
+ * level's service exactly as it injects its own.
+ */
+export declare class PoServerScope {
+  readonly level: PoApiScope;
+  readonly parent: PoServerScope | undefined;
+  readonly root: Context;
+  private readonly children;
+  private readonly bound;
+  private readonly mirrors;
+  private readonly installed;
+  private installs;
+  /** Set once a package's apply never settled, to the bound it overran; its fiber may never finish disposing. */
+  private abandonedTimeoutMs;
+  private notice;
+  private disposing;
+  /** The served mount table, read when a request routes through this level. */
+  private router;
+  /** Kept by the outermost scope only: what each plugin build shares across the whole tree. */
+  private readonly shares;
+  private constructor();
+  /** Opens a scope below `parent`, with every binding visible from its ancestors already published. */
+  static open(level: PoApiScope, parent?: PoServerScope): Promise<PoServerScope>;
+  get disposed(): boolean;
+  /**
+   * Publishes what every package at this level reads: the owner's mount table as `po/server-host`,
+   * and the platform services. They stay for the life of the scope; the owner still disposes the
+   * mount table it handed in.
+   */
+  serve(input: PoServerScopeHost): Promise<void>;
+  /**
+   * Installs packages at this level, each as its own fiber in this root, one at a time.
+   *
+   * Installation only adds. A package installed from the same build (the same plugin object) is
+   * skipped. One whose build changed is disposed and the new build applied; when that fails, the
+   * previous build is applied again. A package missing from `packages` stays installed, because
+   * which packages a session runs is its own composition's choice. Installs into one scope run one
+   * at a time. Resolves with every package installed here, in install order.
+   */
+  install(packages: readonly (PoServerPlugin | LoadedServerPackage)[], options?: PoServerInstallOptions): Promise<readonly string[]>;
+  /**
+   * Binds a contract owned by this level here and in every descendant, including ones opened later.
+   * Settles once every descendant root publishes it. Hosts call this directly; plugins go through
+   * the scope service so the binding follows their fiber.
+   */
+  bind<T>(contract: PoServiceContract<T>, value: T): Promise<() => Promise<void>>;
+  resolve<T>(contract: PoServiceContract<T>): T | undefined;
+  /**
+   * The handler for an API, from this level or the nearest one above it that serves it. An API
+   * declared at a level reaches every level below it, and a level that runs a package from an outer
+   * level leaves that level's root-bound APIs to it; a level that declares the API itself wins.
+   */
+  apiHandler(basePath: string): PoApiHandler | undefined;
+  emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;
+  broadcast<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void;
+  /**
+   * Disposes descendants first, then the packages installed here in reverse install order, then
+   * this root; a binding made here unwinds with its provider.
+   */
+  dispose(): Promise<void>;
+  /**
+   * What the plugin build `owner` shares in this tree, seen from this scope. The outermost scope keeps
+   * one store per build, so every level of one hub sees the same values and no two hubs ever do.
+   */
+  share<TRoots>(owner: object): PoServerPluginShare<TRoots>;
+  private installAll;
+  /** Applies a replaced package's previous build again after its new build failed. */
+  private restore;
+  /** Applies one package as its own fiber, bounded by the factory timeout, and reports how it settled. */
+  private apply;
+  private visible;
+  /** This scope, then each parent out to the root. */
+  private outermost;
+  /** Disposes every value the tree still holds, newest first; a failure is reported and the rest still go. */
+  private disposeShares;
+  private ancestry;
+  private subtree;
+  /**
+   * Publishes a binding into this root and settles once it is live. Idempotent per binding, since a
+   * child opening mid-bind is reached by both `open` and `bind`.
+   */
+  private mirror;
+  private unmirror;
+}
+//#endregion
+//# sourceMappingURL=serverScope.d.mts.map

package/dist/src/server/serverScope.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverScope.d.mts","names":[],"sources":["../../../src/server/serverScope.ts"],"mappings":";;;;;;;;iBAyDiB;;;;;WAKN,MAAM;IAAwB,YAAY,mBAAmB;;;WAE7D,UAAU;;iBAGJ;WACN;WACA;WACA;;iBAGM;WACN,YAAY;;WAEZ;;WAEA,oBAAoB,QAAQ;;;;;;;;;;;qBA8J1B;WAiBA,OAAO;WACP,QAAQ;WAjBV,MAAI;mBACI;mBACA;mBACA;mBACA;UACT;;UAEA;UACA;UACA;;UAEA;;mBAES;UAEV;;SAMM,KAAK,OAAO,YAAY,SAAS,gBAAgB,QAAQ;MAgBlE;;;;;;EASE,MAAM,OAAO,oBAAoB;;;;;;;;;;EAyBvC,QACE,oBAAoB,iBAAiB,wBACrC,UAAS,yBACR;;;;;;EAcG,KAAK,GAAG,UAAU,kBAAkB,IAAI,OAAO,IAAI,cAAc;EAwBvE,QAAQ,GAAG,UAAU,kBAAkB,KAAK;;;;;;EAc5C,WAAW,mBAAmB;EAQ9B,KAAK,gBAAgB,QAAQ,MAAM,MAAM,MAAM,WAAW,OAAO;EAIjE,UAAU,gBAAgB,QAAQ,MAAM,MAAM,MAAM,WAAW,OAAO;;;;;EAQtE,WAAW;;;;;EA0BX,MAAM,QAAQ,gBAAgB,oBAAoB;UAmFpC;;UAyDA;;UAgBA;UAqCN;;UAKA;;UAKM;UAYL;UAKA;;;;;UAUK;UAUA"}

package/dist/src/server/serverScope.mjs

@@ -0,0 +1,510 @@
+import { PO_SERVER_SCOPE_LEVELS, PO_SERVER_SCOPE_SERVICE } from "../schemas/serverScope.mjs";
+import { PO_HEADLESS_OWNER, readPoHeadlessHost } from "../schemas/headless.mjs";
+import { PO_SESSION_FILES_SERVICE, PO_SESSION_TEMP_DIR } from "../services/sessionFiles/index.mjs";
+import { withTimeout } from "./liveImport.mjs";
+import { PO_FS_SERVICE, PO_SESSION_STORAGE_SERVICE, PO_SHELL_SERVICE, PO_SQLITE_SERVICE } from "../schemas/platform.mjs";
+import { PO_SERVER_HOST_SERVICE } from "../schemas/serverPlugin.mjs";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+//#region src/server/serverScope.ts
+/** What one plugin build shares in one tree: its keyed values, and what each scope running it holds. */
+var PluginShare = class {
+	values = /* @__PURE__ */ new Map();
+	running = /* @__PURE__ */ new Map();
+	get idle() {
+		return this.values.size === 0 && this.running.size === 0;
+	}
+};
+const resourceName = (key) => JSON.stringify(typeof key === "string" ? [key] : key);
+const depth = (level) => PO_SERVER_SCOPE_LEVELS.indexOf(level);
+const describe = (error) => error instanceof Error ? error.message : String(error);
+/** Publishes one binding as a native service of the root it is plugged into. */
+function bindingProvider(context, binding) {
+	context.provide(binding.name, binding.value);
+}
+/**
+* The scope service each root publishes.
+*
+* Cordis traceable services rebind `ctx` to the caller, so a binding made through
+* `provide` unwinds with the plugin that made it.
+*/
+var ScopeService = class extends Service {
+	scope;
+	level;
+	constructor(ctx, scope) {
+		super(ctx, PO_SERVER_SCOPE_SERVICE);
+		this.scope = scope;
+		this.level = scope.level;
+	}
+	async provide(contract, value) {
+		return await this.ctx.effect(() => this.scope.bind(contract, value), `po scope provide ${contract.name}`);
+	}
+	resolve(contract) {
+		return this.scope.resolve(contract);
+	}
+	emit(name, ...args) {
+		this.scope.emit(name, ...args);
+	}
+	broadcast(name, ...args) {
+		this.scope.broadcast(name, ...args);
+	}
+	plugin(owner) {
+		return this.scope.share(owner);
+	}
+};
+/**
+* Binds registrations to the Cordis fiber that calls the host service.
+*
+* The host itself is shared by every package at its level, but Cordis traceable
+* services rebind `ctx` to the caller. That lets a package's registration unwind
+* even when `apply` throws before it can return its disposer.
+*/
+var ScopedPoServerHost = class extends Service {
+	host;
+	scope;
+	context;
+	constructor(ctx, host) {
+		super(ctx, PO_SERVER_HOST_SERVICE);
+		this.host = host;
+		this.scope = host.scope;
+		this.context = host.context;
+	}
+	registerApi(api) {
+		const headless = this.scope === "session" ? readPoHeadlessHost(this.ctx) : void 0;
+		if (headless) {
+			const activity = headless.registerActivity({
+				name: `api:${api.basePath}`,
+				start: () => {
+					const registration = this.host.registerApi(api);
+					if (registration.mounted !== true) {
+						registration.dispose();
+						throw new Error(`package API '${api.basePath}' did not mount.`);
+					}
+					return () => {
+						registration.dispose();
+					};
+				}
+			});
+			return {
+				mounted: true,
+				dispose: () => activity.dispose()
+			};
+		}
+		const registration = this.host.registerApi(api);
+		if (registration.mounted !== true) {
+			registration.dispose();
+			throw new Error(`package API '${api.basePath}' did not mount.`);
+		}
+		this.ctx.effect(() => () => registration.dispose(), "server package API registration");
+		return registration;
+	}
+	registerChannel(channel) {
+		const registration = this.host.registerChannel(channel);
+		if (registration.mounted !== true) {
+			registration.dispose();
+			throw new Error(`hub channel '${channel.frameType}' did not mount.`);
+		}
+		this.ctx.effect(() => () => registration.dispose(), "server package channel registration");
+		return registration;
+	}
+	registerMethod = (definition, handler) => {
+		const registration = this.host.registerMethod(definition, handler);
+		if (registration.mounted !== true) {
+			registration.dispose();
+			throw new Error(`plugin method '${definition.service}.${definition.method}' did not mount.`);
+		}
+		this.ctx.effect(() => () => registration.dispose(), "server package method registration");
+		return registration;
+	};
+	mounted() {
+		return this.host.mounted();
+	}
+	mountedChannels() {
+		return this.host.mountedChannels();
+	}
+};
+/** Publishes the host service from inside a root-level plugin, so it unwinds with the scope. */
+function serverHostProvider(context, host) {
+	new ScopedPoServerHost(context, host);
+}
+/** Publishes the platform services from inside a root-level plugin, so they unwind with the scope. */
+function platformProvider(context, input) {
+	const env = input.platform.env(input.cwd);
+	context.provide(PO_FS_SERVICE, env);
+	context.provide(PO_SHELL_SERVICE, env);
+	context.provide(PO_SQLITE_SERVICE, input.platform.sqlite);
+	context.provide(PO_SESSION_STORAGE_SERVICE, input.platform.sessions);
+	if (input.temporaryDirectory !== void 0) context.provide(PO_SESSION_FILES_SERVICE, { temporaryDirectory: input.temporaryDirectory });
+	context.effect(() => () => env.cleanup(BACKGROUND_CONTEXT), "platform execution env");
+}
+/**
+* One level of the server IoC tree: its own cordis root, a parent link, the contracts bound here,
+* and the packages installed here.
+*
+* Separate roots rather than one shared root, because cordis re-checks every fiber of a root on each
+* service change; a hundred sessions in one root would make every change scan all of them. A binding
+* is instead mirrored into each descendant root as a native service, so a plugin injects an outer
+* level's service exactly as it injects its own.
+*/
+var PoServerScope = class PoServerScope {
+	level;
+	parent;
+	root = new Context();
+	children = /* @__PURE__ */ new Set();
+	bound = /* @__PURE__ */ new Map();
+	mirrors = /* @__PURE__ */ new Map();
+	installed = /* @__PURE__ */ new Map();
+	installs = Promise.resolve();
+	/** Set once a package's apply never settled, to the bound it overran; its fiber may never finish disposing. */
+	abandonedTimeoutMs;
+	notice = () => void 0;
+	disposing;
+	/** The served mount table, read when a request routes through this level. */
+	router;
+	/** Kept by the outermost scope only: what each plugin build shares across the whole tree. */
+	shares = /* @__PURE__ */ new Map();
+	constructor(level, parent) {
+		this.level = level;
+		this.parent = parent;
+	}
+	/** Opens a scope below `parent`, with every binding visible from its ancestors already published. */
+	static async open(level, parent) {
+		if (parent?.disposing !== void 0) throw new Error(`The ${parent.level} scope is disposed.`);
+		if (parent !== void 0 && depth(level) <= depth(parent.level)) throw new Error(`A ${level} scope cannot open below a ${parent.level} scope.`);
+		const scope = new PoServerScope(level, parent);
+		parent?.children.add(scope);
+		try {
+			await scope.root.plugin(ScopeService, scope);
+			await Promise.all((parent?.visible() ?? []).map((binding) => scope.mirror(binding)));
+		} catch (error) {
+			await scope.dispose();
+			throw error;
+		}
+		return scope;
+	}
+	get disposed() {
+		return this.disposing !== void 0;
+	}
+	/**
+	* Publishes what every package at this level reads: the owner's mount table as `po/server-host`,
+	* and the platform services. They stay for the life of the scope; the owner still disposes the
+	* mount table it handed in.
+	*/
+	async serve(input) {
+		if (this.disposed) throw new Error(`The ${this.level} scope is disposed.`);
+		if (input.host.scope !== this.level) throw new Error(`A ${input.host.scope} host cannot serve a ${this.level} scope.`);
+		await this.root.plugin(serverHostProvider, input.host);
+		this.router = input.host;
+		const hostContext = input.host.context;
+		const cwd = hostContext?.cwd ?? hostContext?.workspaceRoot ?? input.platform.homeDirectory;
+		await this.root.plugin(platformProvider, {
+			platform: input.platform,
+			cwd,
+			temporaryDirectory: this.level === "session" ? hostContext?.environment?.[PO_SESSION_TEMP_DIR] : void 0
+		});
+	}
+	/**
+	* Installs packages at this level, each as its own fiber in this root, one at a time.
+	*
+	* Installation only adds. A package installed from the same build (the same plugin object) is
+	* skipped. One whose build changed is disposed and the new build applied; when that fails, the
+	* previous build is applied again. A package missing from `packages` stays installed, because
+	* which packages a session runs is its own composition's choice. Installs into one scope run one
+	* at a time. Resolves with every package installed here, in install order.
+	*/
+	install(packages, options = {}) {
+		const run = this.installs.then(() => this.installAll(packages, options));
+		this.installs = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	/**
+	* Binds a contract owned by this level here and in every descendant, including ones opened later.
+	* Settles once every descendant root publishes it. Hosts call this directly; plugins go through
+	* the scope service so the binding follows their fiber.
+	*/
+	async bind(contract, value) {
+		if (this.disposed) throw new Error(`The ${this.level} scope is disposed.`);
+		if (contract.scope !== this.level) throw new Error(`Contract '${contract.name}' belongs to the ${contract.scope} scope and cannot be provided from the ${this.level} scope.`);
+		if (this.bound.has(contract.name)) throw new Error(`Contract '${contract.name}' is already provided in this ${this.level} scope.`);
+		const binding = {
+			name: contract.name,
+			value
+		};
+		this.bound.set(contract.name, binding);
+		const withdraw = async () => {
+			if (this.bound.get(contract.name) !== binding) return;
+			this.bound.delete(contract.name);
+			await Promise.all([...this.subtree()].map((scope) => scope.unmirror(binding)));
+		};
+		try {
+			await Promise.all([...this.subtree()].map((scope) => scope.mirror(binding)));
+		} catch (error) {
+			await withdraw();
+			throw error;
+		}
+		return withdraw;
+	}
+	resolve(contract) {
+		if (depth(contract.scope) > depth(this.level)) throw new Error(`A ${this.level} scope cannot see the ${contract.scope} contract '${contract.name}'.`);
+		for (const scope of this.ancestry()) if (scope.level === contract.scope) return scope.bound.get(contract.name)?.value;
+	}
+	/**
+	* The handler for an API, from this level or the nearest one above it that serves it. An API
+	* declared at a level reaches every level below it, and a level that runs a package from an outer
+	* level leaves that level's root-bound APIs to it; a level that declares the API itself wins.
+	*/
+	apiHandler(basePath) {
+		for (const scope of this.ancestry()) {
+			const handler = scope.router?.handlerFor?.(basePath);
+			if (handler !== void 0) return handler;
+		}
+	}
+	emit(name, ...args) {
+		deliver([...this.ancestry()], name, args);
+	}
+	broadcast(name, ...args) {
+		deliver([...this.subtree()], name, args);
+	}
+	/**
+	* Disposes descendants first, then the packages installed here in reverse install order, then
+	* this root; a binding made here unwinds with its provider.
+	*/
+	dispose() {
+		this.disposing ??= (async () => {
+			await Promise.all([...this.children].map((child) => child.dispose()));
+			this.parent?.children.delete(this);
+			this.mirrors.clear();
+			this.router = void 0;
+			const packages = [...this.installed.values()].reverse();
+			this.installed.clear();
+			for (const { fiber } of packages) await fiber.dispose();
+			const disposal = this.root.fiber.dispose();
+			if (this.abandonedTimeoutMs === void 0) return await disposal;
+			await withTimeout(disposal, this.abandonedTimeoutMs, `${this.level} scope dispose`).catch((error) => this.notice(describe(error)));
+		})().finally(async () => {
+			if (this.parent === void 0) await this.disposeShares();
+		});
+		return this.disposing;
+	}
+	/**
+	* What the plugin build `owner` shares in this tree, seen from this scope. The outermost scope keeps
+	* one store per build, so every level of one hub sees the same values and no two hubs ever do.
+	*/
+	share(owner) {
+		const top = this.outermost();
+		const storeOf = () => {
+			let store = top.shares.get(owner);
+			if (store === void 0) {
+				store = new PluginShare();
+				top.shares.set(owner, store);
+			}
+			return store;
+		};
+		const settle = (store) => {
+			if (store.idle && top.shares.get(owner) === store) top.shares.delete(owner);
+		};
+		return {
+			acquire: async (key, create, dispose) => {
+				if (this.disposed) throw new Error(`The ${this.level} scope is disposed.`);
+				const store = storeOf();
+				const name = resourceName(key);
+				let shared = store.values.get(name);
+				if (shared === void 0) {
+					const created = {
+						value: Promise.resolve().then(create),
+						holders: 0,
+						disposeValue: dispose === void 0 ? void 0 : (value) => dispose(value)
+					};
+					store.values.set(name, created);
+					created.value.catch(() => {
+						if (store.values.get(name) === created) store.values.delete(name);
+						settle(store);
+					});
+					shared = created;
+				}
+				const held = shared;
+				held.holders += 1;
+				let value;
+				try {
+					value = await held.value;
+				} catch (error) {
+					held.holders -= 1;
+					throw error;
+				}
+				let released = false;
+				return {
+					value,
+					release: async () => {
+						if (released) return;
+						released = true;
+						held.holders -= 1;
+						if (held.holders > 0 || store.values.get(name) !== held) return;
+						store.values.delete(name);
+						settle(store);
+						await held.disposeValue?.(value);
+					}
+				};
+			},
+			run: (roots) => {
+				if (this.disposed) throw new Error(`The ${this.level} scope is disposed.`);
+				const store = storeOf();
+				store.running.set(this, roots);
+				return () => {
+					if (store.running.get(this) === roots) store.running.delete(this);
+					settle(store);
+				};
+			},
+			outer: (from) => {
+				const store = top.shares.get(owner);
+				if (store === void 0) return [];
+				const held = [];
+				for (const scope of this.parent?.ancestry() ?? []) if (depth(scope.level) >= depth(from) && store.running.has(scope)) held.push(store.running.get(scope));
+				return held;
+			}
+		};
+	}
+	async installAll(packages, options) {
+		if (this.disposed) throw new Error(`The ${this.level} scope is disposed.`);
+		const notice = options.onNotice ?? (() => {});
+		this.notice = notice;
+		if (packages.some((candidate) => "retained" in candidate && candidate.retained === true) && !readPoHeadlessHost(this.root)) throw new Error("Retained server candidates require a gated headless host");
+		for (const candidate of packages) {
+			const plugin = "declaration" in candidate ? candidate.plugin : candidate;
+			const declaration = "declaration" in candidate ? candidate.declaration : void 0;
+			const name = declaration?.packageName ?? plugin.name;
+			const previous = this.installed.get(name);
+			if (previous?.plugin === plugin) continue;
+			if (previous !== void 0) {
+				this.installed.delete(name);
+				await previous.fiber.dispose();
+			}
+			try {
+				const fiber = await this.apply(name, plugin, declaration, options);
+				this.installed.set(name, {
+					plugin,
+					...declaration === void 0 ? {} : { declaration },
+					fiber
+				});
+			} catch (error) {
+				const message = `server package '${name}' did not install (${describe(error)})`;
+				if (previous !== void 0) {
+					await this.restore(name, previous, options, message);
+					continue;
+				}
+				if (declaration?.required === true && !("initiallyEligible" in candidate && candidate.initiallyEligible === false)) throw new Error(message, { cause: error });
+				notice(message);
+			}
+		}
+		for (const candidate of packages) {
+			const plugin = "declaration" in candidate ? candidate.plugin : candidate;
+			const name = ("declaration" in candidate ? candidate.declaration.packageName : void 0) ?? plugin.name;
+			if (this.installed.get(name)?.plugin !== plugin) continue;
+			for (const contract of plugin.injects?.[this.level] ?? []) if (depth(contract.scope) > depth(this.level) || this.resolve(contract) === void 0) notice(`server package '${name}' waits for contract '${contract.name}', which no ${contract.scope} package provides.`);
+		}
+		return [...this.installed.keys()];
+	}
+	/** Applies a replaced package's previous build again after its new build failed. */
+	async restore(name, previous, options, message) {
+		try {
+			const fiber = await this.apply(name, previous.plugin, previous.declaration, options);
+			this.installed.set(name, {
+				...previous,
+				fiber
+			});
+			this.notice(`${message}; its previous build is restored.`);
+		} catch (rollbackError) {
+			this.notice(`${message}; its previous build could not be restored (${describe(rollbackError)}).`);
+		}
+	}
+	/** Applies one package as its own fiber, bounded by the factory timeout, and reports how it settled. */
+	async apply(name, plugin, declaration, options) {
+		const startedAt = Date.now();
+		const timeoutMs = options.factoryTimeoutMs ?? 1e4;
+		const settled = (outcome) => options.onPackageSettled?.({
+			packageName: name,
+			durationMs: Date.now() - startedAt,
+			outcome
+		});
+		let fiber;
+		let applySettled = false;
+		try {
+			fiber = (declaration ? this.root.extend({ [PO_HEADLESS_OWNER]: declaration }) : this.root).plugin(plugin);
+			const applied = fiber.await();
+			const markSettled = () => {
+				applySettled = true;
+			};
+			applied.then(markSettled, markSettled);
+			await withTimeout(applied, timeoutMs, `server package '${name}' apply`);
+			settled("installed");
+			return fiber;
+		} catch (error) {
+			settled(fiber && !applySettled ? "timed_out" : "failed");
+			if (fiber && !applySettled) {
+				this.abandonedTimeoutMs = Math.max(this.abandonedTimeoutMs ?? 0, timeoutMs);
+				fiber.dispose().catch((disposeError) => this.notice(`abandoned server package '${name}' did not dispose (${describe(disposeError)})`));
+			} else await fiber?.dispose();
+			throw error;
+		}
+	}
+	visible() {
+		return [...this.parent?.visible() ?? [], ...this.bound.values()];
+	}
+	/** This scope, then each parent out to the root. */
+	outermost() {
+		return this.parent === void 0 ? this : this.parent.outermost();
+	}
+	/** Disposes every value the tree still holds, newest first; a failure is reported and the rest still go. */
+	async disposeShares() {
+		const values = [...this.shares.values()].flatMap((store) => [...store.values.values()]).reverse();
+		this.shares.clear();
+		for (const shared of values) try {
+			await shared.disposeValue?.(await shared.value);
+		} catch (error) {
+			this.notice(`a shared server value did not dispose (${describe(error)})`);
+		}
+	}
+	*ancestry() {
+		yield this;
+		if (this.parent !== void 0) yield* this.parent.ancestry();
+	}
+	*subtree() {
+		if (this.disposed) return;
+		yield this;
+		for (const child of this.children) yield* child.subtree();
+	}
+	/**
+	* Publishes a binding into this root and settles once it is live. Idempotent per binding, since a
+	* child opening mid-bind is reached by both `open` and `bind`.
+	*/
+	async mirror(binding) {
+		if (this.disposed) return;
+		let fiber = this.mirrors.get(binding);
+		if (fiber === void 0) {
+			fiber = this.root.plugin(bindingProvider, binding);
+			this.mirrors.set(binding, fiber);
+		}
+		await fiber.await();
+	}
+	async unmirror(binding) {
+		const fiber = this.mirrors.get(binding);
+		this.mirrors.delete(binding);
+		if (!this.disposed) await fiber?.dispose();
+	}
+};
+/** Every scope receives the event even when an earlier one's listener throws. */
+function deliver(scopes, name, args) {
+	const errors = [];
+	for (const scope of scopes) {
+		if (scope.disposed) continue;
+		try {
+			scope.root.events.emit(name, ...args);
+		} catch (error) {
+			errors.push(error);
+		}
+	}
+	if (errors.length > 0) throw new AggregateError(errors, `${errors.length} scope listener(s) of '${name}' failed.`);
+}
+//#endregion
+export { PoServerScope };
+
+//# sourceMappingURL=serverScope.mjs.map