@dsh-electron/dsh-plugin-multi-root-workspace 0.1.0

package/lib/command.js

@@ -0,0 +1,2 @@
+import { a as renderRootsReport, i as parseFoldersCommand, n as apply, o as revealArgv, r as inject, t as COMMAND_NAME } from "./command-BSkrYOAf.js";
+export { COMMAND_NAME, apply, inject, parseFoldersCommand, renderRootsReport, revealArgv };

package/lib/fs-D7UoCb7T.js

@@ -0,0 +1,152 @@
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+import { stat } from "node:fs/promises";
+import { dirname, sep } from "node:path";
+//#region src/containment.ts
+const MISSING_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+//#endregion
+//#region src/fs.ts
+/**
+* Sandbox-enforcing filesystem backend over the multi-root scope. Registers as
+* `ctx.fs`; `ctx.sandboxPolicy` still owns the mode and the primary root, and
+* this class only widens the writable root set with the scope's additional
+* roots.
+*/
+var MultiRootFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy", "multiRootScope"];
+	defaultMode;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* Fence the write by the per-call policy, then delegate to the inherited
+	* atomic write.
+	* @param target - the resolved target to write.
+	* @param content - the full new file content.
+	* @param expected - the write intent guarding the write; omit for unconditional.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the write outcome from the inherited backend.
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* Fence the edit by the per-call policy, then delegate to the inherited
+	* atomic edit.
+	* @param target - the resolved target to edit.
+	* @param edit - the literal search/replace request.
+	* @param expected - the version guard; omit for an unconditional edit.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the edit outcome from the inherited backend.
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/**
+	* The writable roots of one workspace-write call: the upstream derivation
+	* (primary root plus the platform temp areas, canonical and deduplicated)
+	* widened by the scope's additional roots, in scope order.
+	* @param policy - the per-call policy.
+	* @param scope - the scope resolved once for this call; both the fence and
+	*   the denial message below share it instead of re-resolving.
+	* @returns the canonical writable roots; empty under `read-only`.
+	*/
+	rootsFor(policy, scope) {
+		const roots = writableRoots(policy);
+		if (roots.length === 0) return roots;
+		for (const root of scope.additionalRoots) if (!roots.includes(root)) roots.push(root);
+		return roots;
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the EXACT target the
+	* mutation must use, so the checked identity is the mutated one (no
+	* check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+	* re-canonicalizes NOW (reflecting a concurrently swapped symlink ancestor),
+	* requires containment under one of the scope's writable roots, and returns
+	* THAT fresh target; `danger-full-access` returns the caller's target unfenced.
+	* @param target - the resolved target about to be mutated.
+	* @param sandboxPolicy - the per-call policy; omit for the deployment fallback.
+	* @returns the fresh canonical target the mutation must use.
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await this.resolve(target.displayPath);
+		const scope = this.ctx.multiRootScope.resolve(policy);
+		const roots = this.rootsFor(policy, scope);
+		let contained = false;
+		for (const root of roots) if (await isPathUnder(fresh.targetKey, root)) {
+			contained = true;
+			break;
+		}
+		if (!contained) {
+			const denial = `cannot write "${target.displayPath}": file access denied under workspace-write mode`;
+			throw new FsError(scope.additionalRoots.length === 0 ? denial : `${denial}; allowed roots: ${roots.join(", ")}`, "FS_SANDBOX_DENIED");
+		}
+		return fresh;
+	}
+};
+//#endregion
+export { MultiRootFileSystem as t };

package/lib/fs.js

@@ -0,0 +1,2 @@
+import { t as MultiRootFileSystem } from "./fs-D7UoCb7T.js";
+export { MultiRootFileSystem, MultiRootFileSystem as default };

package/lib/index.js

@@ -0,0 +1,17 @@
+import { t as MultiRootFileSystem } from "./fs-D7UoCb7T.js";
+import { t as MultiRootSandboxProvider } from "./sandbox-BhuMTDgH.js";
+import { MultiRootScopeService, renderWorkspaceRootsContext, sanitizeAdditionalRoots } from "./scope.js";
+import { a as classifyStoredRoots, c as indexedStatuses, f as resolveRootRef, i as canonicalRoot, l as isCanonicallyUnder, n as additionalRootId, p as validateRootCandidate, r as availableRoots, s as expandRootInput, t as RootValidationError, u as removeStatusAt } from "./roots-DyT2jgEP.js";
+import { DOMAIN_NAME, MAX_ALIAS_LENGTH, MultiRootRegistry, multiRootDomainSpec } from "./registry.js";
+import { a as renderRootsReport, c as PANEL_ENDPOINTS, d as parseRootsView, i as parseFoldersCommand, l as parsePanelCall, o as revealArgv, s as PANEL_CHANNEL, t as COMMAND_NAME, u as parseRevealedView } from "./command-BSkrYOAf.js";
+//#region src/index.ts
+/**
+* Carrier plugin face for the bare-package-name loader row (see the module
+* doc). It deliberately provides nothing: every host responsibility is owned
+* by a subpath entry, and this row exists only so the web client-module scan
+* can locate the package root and read its `dsh.client` declaration.
+*/
+const inject = [];
+function apply() {}
+//#endregion
+export { COMMAND_NAME, DOMAIN_NAME, MAX_ALIAS_LENGTH, MultiRootFileSystem, MultiRootRegistry, MultiRootSandboxProvider, MultiRootScopeService, PANEL_CHANNEL, PANEL_ENDPOINTS, RootValidationError, additionalRootId, apply, availableRoots, canonicalRoot, classifyStoredRoots, expandRootInput, indexedStatuses, inject, isCanonicallyUnder, multiRootDomainSpec, parseFoldersCommand, parsePanelCall, parseRevealedView, parseRootsView, removeStatusAt, renderRootsReport, renderWorkspaceRootsContext, resolveRootRef, revealArgv, sanitizeAdditionalRoots, validateRootCandidate };

package/lib/registry.js

@@ -0,0 +1,466 @@
+import { a as classifyStoredRoots, d as resolveRootIndex, i as canonicalRoot, n as additionalRootId, p as validateRootCandidate, r as availableRoots, t as RootValidationError, u as removeStatusAt } from "./roots-DyT2jgEP.js";
+import { Service } from "@deepseek-ai/cordis";
+import { randomUUID } from "node:crypto";
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+import { z } from "zod";
+//#region src/registry.ts
+/**
+* `MultiRootRegistry`: the durable answer to "which directories are extra
+* writable roots of this workspace".
+*
+* It is the M3 data source the M2 providers were already written against: the
+* registry owns the records, validates every mutation, re-validates everything
+* it reads back, and feeds the ONE place enforcement resolves from
+* (`ctx.multiRootScope`). Neither provider learns that a registry exists —
+* `setAdditionalRoots()` stays the scope's only write port.
+*
+* Four deliberate properties:
+*
+* - **Only usable roots are granted.** A registered directory that is absent
+*   right now stays registered and is reported as `missing`, but is withheld
+*   from the scope: handing a nonexistent root to bwrap or Landlock would fail
+*   the confined command instead of merely not granting it. A registration
+*   whose path now resolves to a DIFFERENT directory is `redirected` and is
+*   withheld for the same reason it was never granted: re-resolving a path is
+*   not re-authorizing it (see `src/scope.ts`).
+* - **Nothing is deleted on the operator's behalf.** A record that violates a
+*   rule is reported as `invalid` and excluded from the scope; it disappears
+*   only when the operator removes it (or when the store is repaired). Storage
+*   that cannot be parsed at all is backed up and skipped by the domain layer,
+*   with a warning.
+* - **Mutations are serialized per primary root.** Every mutation runs its
+*   whole read → validate → persist sequence inside one queue per key. The
+*   storage domain serializes individual `put()`/`delete()` calls, which is not
+*   enough: two concurrent `add()` calls would both read the same snapshot and
+*   the later write would drop the earlier one, and a removal racing an add
+*   could write a deleted record back.
+* - **Reads re-check, but never write.** {@link MultiRootRegistry.refresh} is
+*   the one revalidation entry point the command and the panel both call: it
+*   re-stats and re-canonicalizes every record, republishes the scope, and
+*   leaves storage untouched — a read must not rewrite the store, and a
+*   read-only refresh must not resurrect anything.
+*
+* @module @dsh-electron/dsh-plugin-multi-root-workspace/registry
+*/
+/** The domain name; also the store file stem (`$DSH_HOME/storages/<name>.json`). */
+const DOMAIN_NAME = "multi_root_workspace";
+/** The single table name inside the domain. */
+const TABLE_NAME = "roots";
+/** Longest accepted display alias. */
+const MAX_ALIAS_LENGTH = 120;
+/** One persisted root record. `zod` validates it at the durable boundary. */
+const persistedRoot = z.object({
+	id: z.string().min(1),
+	path: z.string().min(1),
+	recordedPath: z.string().min(1).optional(),
+	alias: z.string().optional(),
+	addedAt: z.string().min(1)
+});
+/**
+* One primary root's whole registration list. The domain's `single` layout
+* stores the entire unit as one document, so keys stay opaque strings — which
+* is exactly what lets the canonical primary root itself be the key.
+*/
+const persistedPrimaryRoot = z.object({ roots: z.array(persistedRoot) });
+/**
+* The domain declaration: version 1, `single` layout, one `roots` table keyed
+* by the canonical primary root. Records that fail validation are backed up and
+* skipped rather than blocking the whole harness from starting (see
+* docs/decisions/ADR-0004).
+*/
+const multiRootDomainSpec = defineDomain({
+	name: DOMAIN_NAME,
+	version: 1,
+	invalidRecords: "backup-and-skip",
+	tables: { roots: domainTable(persistedPrimaryRoot) }
+});
+/** The registry service: `ctx.multiRootRegistry`. */
+var MultiRootRegistry = class extends Service {
+	static inject = ["storageDomain", "multiRootScope"];
+	/** The open table; present once the service has started. */
+	table;
+	/** Why the store is unusable, when it is; every mutation then fails loudly. */
+	failure;
+	/** Last classified status list per canonical primary root. */
+	cache = /* @__PURE__ */ new Map();
+	/** Signature of the last published grant per key, so a no-op refresh stays a no-op. */
+	published = /* @__PURE__ */ new Map();
+	/** One promise chain per canonical primary root: mutations never interleave. */
+	chains = /* @__PURE__ */ new Map();
+	/** Change listeners, keyed by their own disposer identity. */
+	listeners = /* @__PURE__ */ new Set();
+	/**
+	* @param ctx - the host context; `storageDomain` and `multiRootScope` are injected.
+	*/
+	constructor(ctx) {
+		super(ctx, "multiRootRegistry");
+	}
+	/**
+	* Open the domain and publish every stored root into the scope.
+	*
+	* A store this build cannot read (corrupt records, a version written by a
+	* different plugin version) is reported loudly and degrades to the empty
+	* root set instead of failing activation: granting nothing is the safe
+	* direction, and a broken side store must not keep the whole harness from
+	* starting. Every mutation then reports `storage-unavailable` with that
+	* reason until the file is repaired or removed.
+	*/
+	async [Service.init]() {
+		let domain;
+		try {
+			domain = await this.ctx.storageDomain.open(multiRootDomainSpec);
+		} catch (error) {
+			this.failure = `${DOMAIN_NAME}: ${error instanceof Error ? error.message : String(error)}`;
+			this.ctx.logger.error(`multi-root-workspace: cannot open the root registry store (${DOMAIN_NAME}); no additional root is granted until it is repaired or removed: ${this.failure}`);
+			return;
+		}
+		this.ctx.effect(() => () => domain.close(), "multi-root-registry: domain close");
+		this.table = domain.table(TABLE_NAME);
+		for (const [primaryRoot, record] of this.table.entries()) this.accept(primaryRoot, record);
+	}
+	/**
+	* Why the store is unusable, when it is. Surfaces show this instead of a
+	* silently empty list, so an operator can tell "no roots configured" from
+	* "the configuration could not be read".
+	* @returns the recorded failure text, or `undefined` while the store is healthy.
+	*/
+	get unavailable() {
+		return this.failure;
+	}
+	/**
+	* Every registration of one primary root, in registry order, as last
+	* classified. A READ of the in-memory state: it never touches the filesystem
+	* and never writes. Surfaces that must re-check the directories first call
+	* {@link MultiRootRegistry.refresh}.
+	* @param primaryRoot - the session workspace root (any spelling).
+	* @returns the statuses; empty when nothing is registered.
+	*/
+	list(primaryRoot) {
+		return this.statusesOf(canonicalRoot(primaryRoot));
+	}
+	/**
+	* Re-examine every registration of one primary root WITHOUT writing storage:
+	* re-`stat` every directory, re-resolve every path against its recorded
+	* directory, re-judge every rule, then republish the scope and notify
+	* listeners.
+	*
+	* This is the one revalidation entry point the command (`/workspace-folders
+	* list`) and the panel (`list` endpoint) both call, so "what the list shows"
+	* and "what is granted" cannot drift: a directory deleted after registration
+	* becomes `missing` and loses its grant, and a directory that came back is
+	* granted again — without either surface asking for a restart.
+	*
+	* The serialized queue is shared with the mutations, so a refresh never
+	* interleaves with a write that is mid-flight.
+	* @param primaryRoot - the session workspace root to re-check.
+	* @returns the refreshed status list.
+	*/
+	async refresh(primaryRoot) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, () => this.reclassify(key));
+	}
+	/**
+	* Registers one additional root.
+	* @param primaryRoot - the session workspace root the root belongs to.
+	* @param input - the directory and optional alias.
+	* @returns the updated status list.
+	* @throws {RootValidationError} when the candidate violates a root rule.
+	*/
+	async add(primaryRoot, input) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, async () => {
+			const statuses = this.statusesOf(key);
+			const canonical = validateRootCandidate(input.path, {
+				primaryRoot: key,
+				existing: availableRoots(statuses)
+			});
+			const alias = normalizeAlias(input.alias);
+			const revived = statuses.findIndex((status) => status.path === canonical || canonicalRoot(status.path) === canonical);
+			const next = revived === -1 ? [...statuses, {
+				id: additionalRootId(randomUUID()),
+				path: canonical,
+				recordedPath: canonical,
+				state: "available",
+				...alias === void 0 ? {} : { alias },
+				addedAt: (/* @__PURE__ */ new Date()).toISOString()
+			}] : statuses.map((status, index) => index === revived ? {
+				...status,
+				path: canonical,
+				recordedPath: canonical,
+				addedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				...alias === void 0 ? {} : { alias }
+			} : status);
+			return await this.persist(key, next);
+		});
+	}
+	/**
+	* Remove one registration.
+	* @param primaryRoot - the session workspace root the root belongs to.
+	* @param ref - which registered root to remove.
+	* @returns the updated status list.
+	* @throws {RootValidationError} `not-found` when the reference matches nothing.
+	*/
+	async remove(primaryRoot, ref) {
+		return await this.removeAt(primaryRoot, ref);
+	}
+	/**
+	* Remove exactly one registration — the one the reference names.
+	*
+	* Unlike a filter by id, this removes a single record, so a store holding two
+	* records that share an id can be cleaned up one entry at a time instead of
+	* losing both to one click.
+	* @param primaryRoot - the session workspace root the root belongs to.
+	* @param ref - which registered root to remove.
+	* @returns the updated status list.
+	* @throws {RootValidationError} `not-found` when the reference matches nothing.
+	*/
+	async removeAt(primaryRoot, ref) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, async () => await this.persist(key, removeStatusAt(this.statusesOf(key), ref)));
+	}
+	/**
+	* Set or clear one registration's display alias.
+	* @param primaryRoot - the session workspace root the root belongs to.
+	* @param ref - which registered root to rename.
+	* @param alias - the new alias; empty or absent clears it.
+	* @returns the updated status list.
+	* @throws {RootValidationError} `not-found`/`invalid-alias`.
+	*/
+	async setAlias(primaryRoot, ref, alias) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, async () => {
+			const statuses = this.statusesOf(key);
+			const targetIndex = resolveRootIndex(statuses, ref);
+			const normalized = normalizeAlias(alias);
+			const next = statuses.map((status, index) => {
+				if (index !== targetIndex) return status;
+				const { alias: _dropped, ...rest } = status;
+				return normalized === void 0 ? rest : {
+					...rest,
+					alias: normalized
+				};
+			});
+			return await this.persist(key, next);
+		});
+	}
+	/**
+	* Move one registration within the display order.
+	* @param primaryRoot - the session workspace root the root belongs to.
+	* @param ref - which registered root to move.
+	* @param beforeRef - the anchor to move in front of; absent moves it to the end.
+	* @returns the updated status list.
+	* @throws {RootValidationError} `not-found` when either reference matches nothing.
+	*/
+	async move(primaryRoot, ref, beforeRef) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, async () => {
+			const statuses = this.statusesOf(key);
+			const targetIndex = resolveRootIndex(statuses, ref);
+			const anchorIndex = beforeRef === void 0 ? void 0 : resolveRootIndex(statuses, beforeRef);
+			if (anchorIndex === targetIndex) return statuses;
+			const target = statuses[targetIndex];
+			const without = statuses.filter((_status, index) => index !== targetIndex);
+			const adjustedAnchor = anchorIndex === void 0 ? without.length : anchorIndex - (targetIndex < anchorIndex ? 1 : 0);
+			const next = [
+				...without.slice(0, adjustedAnchor),
+				target,
+				...without.slice(adjustedAnchor)
+			];
+			return await this.persist(key, next);
+		});
+	}
+	/**
+	* Re-examine every registration of one primary root and persist what the
+	* re-examination produced — {@link MultiRootRegistry.refresh} plus one durable
+	* write. The recovery path after a directory was restored by hand, and the
+	* only read-shaped operation that is allowed to touch the store.
+	* @param primaryRoot - the session workspace root to re-check.
+	* @returns the refreshed status list.
+	*/
+	async recheck(primaryRoot) {
+		const key = canonicalRoot(primaryRoot);
+		return await this.serialize(key, async () => await this.persist(key, this.reclassify(key)));
+	}
+	/**
+	* Observe registry changes.
+	* @param listener - called with the canonical primary root after each durable change.
+	* @returns the disposer that stops observing.
+	*/
+	onChange(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/**
+	* The scope the registry publishes: only usable roots, in registry order.
+	* @param primaryRoot - the session workspace root (any spelling).
+	* @returns the canonical paths of every `available` root.
+	*/
+	granted(primaryRoot) {
+		return availableRoots(this.statusesOf(canonicalRoot(primaryRoot)));
+	}
+	/**
+	* The scope the registry publishes: only usable roots, in registry order.
+	* @param policy - the per-call policy; its workspace root is the primary root.
+	* @returns the granted canonical roots.
+	*/
+	grantedFor(policy) {
+		return this.granted(policy.workspaceRoot);
+	}
+	/** Classify one stored record set and cache it. */
+	accept(primaryRoot, record) {
+		const key = canonicalRoot(primaryRoot);
+		const statuses = classifyStoredRoots(key, record.roots.map(toRegisteredRoot));
+		this.cache.set(key, statuses);
+		this.publish(key, statuses);
+		return statuses;
+	}
+	/**
+	* The statuses of one key, from memory where possible: the cache, else what
+	* storage holds, else empty. A cached answer is never re-checked here — that
+	* is {@link MultiRootRegistry.reclassify}, which the read surfaces and
+	* {@link MultiRootRegistry.refresh} call deliberately.
+	*/
+	statusesOf(key) {
+		const cached = this.cache.get(key);
+		if (cached !== void 0) return cached;
+		const record = this.lookupRecords(key);
+		if (record === void 0) return [];
+		return this.accept(key, record);
+	}
+	/**
+	* The stored record set of one key, or `undefined` when there is none (or
+	* when the store itself could not be read: an unusable store reads as
+	* "nothing registered" so reads stay answerable and the surfaces can explain
+	* the situation, while every write fails loudly in `requireTable()`).
+	*/
+	lookupRecords(key) {
+		if (this.failure !== void 0) return void 0;
+		return this.requireTable().get(key);
+	}
+	/**
+	* Re-classify one key from its stored records: every directory is `stat`ed
+	* again and every path is resolved again against its recorded canonical
+	* directory. Updates the cache, republishes the scope, and returns the new
+	* list — the shared body of the read-path re-checks.
+	*/
+	reclassify(key) {
+		const record = this.lookupRecords(key);
+		if (record === void 0) {
+			this.cache.set(key, []);
+			this.publish(key, []);
+			return [];
+		}
+		return this.accept(key, record);
+	}
+	/**
+	* Persist one status list, then republish it into the scope and to listeners.
+	* The durable write happens first: a failed write must not leave the running
+	* scope granting something storage does not hold.
+	*/
+	async persist(key, statuses) {
+		const table = this.requireTable();
+		if (statuses.length === 0) await table.delete(key);
+		else {
+			const durable = persistedPrimaryRoot.parse({ roots: statuses.map(toPersistedRoot) });
+			await table.put(key, durable);
+		}
+		const classified = statuses.length === 0 ? [] : classifyStoredRoots(key, statuses.map(toRegisteredRoot));
+		this.cache.set(key, classified);
+		this.publish(key, classified);
+		return classified;
+	}
+	/**
+	* Run one job for one primary root after every job already queued for that
+	* root. The whole read → validate → write sequence belongs inside the job:
+	* the storage domain serializes individual writes, so without this the loser
+	* of a race reads a snapshot that is already stale and writes it back.
+	*/
+	async serialize(key, job) {
+		const run = (this.chains.get(key) ?? Promise.resolve()).then(job);
+		const tail = run.then(() => void 0, () => void 0);
+		this.chains.set(key, tail);
+		try {
+			return await run;
+		} finally {
+			if (this.chains.get(key) === tail) this.chains.delete(key);
+		}
+	}
+	/**
+	* Push one status list into the scope and notify listeners.
+	*
+	* What is published is the effective GRANT — only `available` roots, so a
+	* withheld registration can never reach a provider. When the grant and the
+	* withheld set are unchanged (the common case for a read-path refresh on a
+	* healthy workspace) the scope is left alone and no listener fires: a refresh
+	* exists to keep the two in sync, not to churn on every listing — and, since
+	* the scope rebuilds its root table on each call, skipping the no-op write is
+	* also what keeps the read path cheap.
+	*/
+	publish(key, statuses) {
+		const withheld = statuses.filter((status) => status.state !== "available");
+		const signature = [...statuses.filter((status) => status.state === "available").map((status) => `available:${status.recordedPath}`), ...withheld.map((status) => `${status.state}:${status.path}`)].join("\n");
+		if (this.published.get(key) === signature) return;
+		this.published.set(key, signature);
+		const effective = statuses.flatMap((status) => {
+			if (status.state !== "available" || status.recordedPath === void 0) return [];
+			return [{
+				id: status.id,
+				path: status.path,
+				recordedPath: status.recordedPath,
+				...status.alias === void 0 ? {} : { alias: status.alias }
+			}];
+		});
+		this.ctx.multiRootScope.setAdditionalRoots(key, effective);
+		if (withheld.length > 0) this.ctx.logger.warn(`multi-root-workspace: ${withheld.length} registered root(s) of ${key} are not writable right now (${withheld.map((status) => `${status.path}: ${status.state}`).join(", ")}); they stay registered and are reported by /workspace-folders`);
+		for (const listener of this.listeners) listener(key);
+	}
+	/**
+	* The open table.
+	* @returns the live table.
+	* @throws {RootValidationError} `storage-unavailable` when the store could
+	*   not be opened at activation, or the service has not started.
+	*/
+	requireTable() {
+		if (this.failure !== void 0) throw new RootValidationError("storage-unavailable", `the root registry store is unavailable (${this.failure}); remove or repair \$DSH_HOME/storages/multi_root_workspace.json and restart dsh`);
+		if (this.table === void 0) throw new Error("multi-root registry is not started yet");
+		return this.table;
+	}
+};
+/** Project one status back to the durable record shape. */
+function toPersistedRoot(status) {
+	return {
+		id: status.id,
+		path: status.path,
+		...status.recordedPath === void 0 || status.recordedPath === "" ? {} : { recordedPath: status.recordedPath },
+		...status.alias === void 0 ? {} : { alias: status.alias },
+		addedAt: status.addedAt
+	};
+}
+/** Recover the registered-root view of a stored record entry. */
+function toRegisteredRoot(entry) {
+	return {
+		id: additionalRootId(entry.id),
+		path: entry.path,
+		...entry.recordedPath === void 0 ? {} : { recordedPath: entry.recordedPath },
+		...entry.alias === void 0 ? {} : { alias: entry.alias },
+		addedAt: entry.addedAt
+	};
+}
+/**
+* Validate and normalize an optional display alias.
+* @param alias - the operator input; empty means "no alias".
+* @returns the trimmed alias, or `undefined`.
+* @throws {RootValidationError} `invalid-alias` for control characters or an over-long value.
+*/
+function normalizeAlias(alias) {
+	if (alias === void 0) return void 0;
+	const trimmed = alias.trim();
+	if (trimmed === "") return void 0;
+	if (/[\u0000-\u001f\u007f]/.test(trimmed)) throw new RootValidationError("invalid-alias", "an alias must not contain control characters");
+	if (trimmed.length > 120) throw new RootValidationError("invalid-alias", `an alias must be at most 120 characters`);
+	return trimmed;
+}
+//#endregion
+export { DOMAIN_NAME, MAX_ALIAS_LENGTH, MultiRootRegistry, MultiRootRegistry as default, TABLE_NAME, multiRootDomainSpec };