@yugoo-design/dsh-design-studio 0.1.2 → 0.2.0

package/lib/node.js

@@ -0,0 +1,2159 @@
+import { a as readStudioArchiveResource, i as exportStudioSourceArchive, n as normalizeStudioInstanceChanges, s as finalizeStudioPanelPreview, t as STUDIO_INSTANCE_CHANGE_LIMITS } from "./instance-changes-RvOGeBaE.js";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadDesignBundle, loadDesignKit, parseFrontmatter, parseKitMounts, parseMindsetSkillNames } from "@yugoo-design/dsh-design-core";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, realpath, rename, rmdir, unlink } from "node:fs/promises";
+import { isMap, isScalar, isSeq, parse, parseDocument, stringify } from "yaml";
+//#region src/node/studio-panel-drafts.mjs
+/** Atomic local source storage and retained trial captures. No project writes. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const HASH = /^[0-9a-f]{64}$/;
+const MAX_SOURCE_BYTES = 16777216;
+const MAX_DOCUMENT_BYTES = 2097152;
+const inside = (root, path) => {
+	const rel = relative(root, path);
+	return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+};
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const moveToSystemTrash = async (file) => {
+	const { default: trash } = await import("trash");
+	await trash([file], { glob: false });
+};
+/** Existing namespaces preserve saved source and historical trial data. */
+async function createStudioDraftPorts({ stateRoot, kitRoot, readInstalledKit, readInstalledBundle, moveToTrash = moveToSystemTrash }, kind) {
+	if (!["panel", "instance"].includes(kind)) throw new Error("Select the Panel history or instance source namespace.");
+	if (!isAbsolute(stateRoot)) throw new Error("Studio requires an explicit absolute state directory.");
+	if (kind === "instance" && typeof moveToTrash !== "function") throw new Error("Studio requires a system trash adapter.");
+	const kitRootReal = kind === "instance" && kitRoot === void 0 ? void 0 : await realpath(kitRoot);
+	if (kitRootReal && inside(kitRootReal, resolve(stateRoot))) throw new Error("Studio drafts must not live inside the installed Kit.");
+	await mkdir(stateRoot, {
+		recursive: true,
+		mode: 448
+	});
+	const state = await realpath(stateRoot);
+	const root = join(state, `studio-${kind}-drafts`);
+	const format = `studio-${kind}-draft/v1`;
+	if (kitRootReal && inside(kitRootReal, root)) throw new Error("Studio drafts must not live inside the installed Kit.");
+	await mkdir(root, {
+		recursive: true,
+		mode: 448
+	});
+	if ((await lstat(root)).isSymbolicLink()) throw new Error("Studio storage cannot be a symlink.");
+	const snapshots = join(root, "snapshots");
+	await mkdir(snapshots, { mode: 448 }).catch((error) => {
+		if (error.code !== "EEXIST") throw error;
+	});
+	if (!(await lstat(snapshots)).isDirectory() || (await lstat(snapshots)).isSymbolicLink()) throw new Error("Unsafe Studio snapshot directory.");
+	const withLock = async (operation) => {
+		const lock = join(root, "write.lock");
+		try {
+			await mkdir(lock, { mode: 448 });
+		} catch (error) {
+			if (error.code === "EEXIST") throw new Error("Studio is being saved elsewhere. Retry; after a crash, stop Studio before clearing its empty write.lock directory.");
+			throw error;
+		}
+		try {
+			return await operation();
+		} finally {
+			await rmdir(lock);
+		}
+	};
+	const readRegular = async (file, limit) => {
+		const info = await lstat(file);
+		if (!info.isFile() || info.isSymbolicLink() || info.size > limit) throw new Error("Invalid or oversized Studio file.");
+		return readFile(file, "utf8");
+	};
+	const writeAtomic = async (file, text) => {
+		const temporary = join(root, `${randomUUID()}.tmp`);
+		let handle;
+		try {
+			handle = await open(temporary, "wx", 384);
+			await handle.writeFile(text, "utf8");
+			await handle.sync();
+			await handle.close();
+			handle = void 0;
+			await rename(temporary, file);
+		} finally {
+			await handle?.close();
+			await unlink(temporary).catch((error) => {
+				if (error.code !== "ENOENT") throw error;
+			});
+		}
+	};
+	const draftPath = (id) => {
+		if (typeof id !== "string" || !UUID.test(id)) throw new Error("Invalid Studio source identity.");
+		return join(root, `${id}.json`);
+	};
+	const read = async (id) => {
+		const record = JSON.parse(await readRegular(draftPath(id), MAX_DOCUMENT_BYTES));
+		const pin = (value) => typeof value?.name === "string" && typeof value?.version === "string";
+		const validContent = kind === "panel" ? typeof record.panelSource === "string" && typeof record.sampleSource === "string" && pin(record.kit) && pin(record.bundle) : ["kit", "bundle"].includes(record.kind) && (record.recordVersion === 2 ? pin(record[record.kind]) && typeof record.sourceId === "string" && (record.current === true || record.sourceId === `local:${record.kind}:${record[record.kind].name}`) && (record.kind !== "bundle" || typeof record.runtimeName === "string") : (record.recordVersion === void 0 || record.recordVersion === 1) && pin(record.source?.kit) && (record.kind !== "bundle" || pin(record.source?.bundle) && typeof record.bundlePath === "string")) && typeof record.title?.zh === "string" && typeof record.title?.en === "string" && record.overlays !== null && typeof record.overlays === "object" && !Array.isArray(record.overlays) && Object.values(record.overlays).every((value) => typeof value === "string") && Array.isArray(record.mounts) && record.mounts.every((mount) => pin(mount.bundle)) && (record.recordVersion !== 2 || record.mounts.every((mount) => typeof mount.bindingKey === "string" && HASH.test(mount.bundle.source?.snapshot) && typeof mount.bundle.source?.sourceId === "string" && (mount.bundle.instanceId === void 0 || UUID.test(mount.bundle.instanceId)) && (mount.bundle.revision === void 0 || Number.isSafeInteger(mount.bundle.revision) && mount.bundle.revision >= 0)));
+		if (record.format !== format || record.id !== id || !Number.isSafeInteger(record.revision) || record.revision < 0 || !HASH.test(record.baseSnapshot) || !validContent) throw new Error("Invalid Studio source record.");
+		const { format: _format, ...value } = record;
+		if (kind === "instance") delete value.confirmed;
+		return value;
+	};
+	const persist = async (record) => {
+		if (kind === "instance") {
+			const { confirmed: _confirmed, ...source } = record;
+			record = source;
+		}
+		const text = JSON.stringify({
+			format,
+			...record
+		});
+		if (Buffer.byteLength(text) > MAX_DOCUMENT_BYTES) throw new Error("Studio source record exceeds 2 MiB.");
+		await writeAtomic(draftPath(record.id), text);
+		return record;
+	};
+	const repository = {
+		read,
+		async list() {
+			const ids = (await readdir(root)).filter((name) => name.endsWith(".json") && UUID.test(name.slice(0, -5))).sort();
+			return Promise.all(ids.map((name) => read(name.slice(0, -5))));
+		},
+		create: (content) => withLock(() => createUnlocked(content)),
+		replace: (id, expectedRevision, content) => withLock(() => replaceUnlocked(id, expectedRevision, content))
+	};
+	const createUnlocked = async (content) => {
+		return persist({
+			...content,
+			id: randomUUID(),
+			revision: 0
+		});
+	};
+	const replaceUnlocked = async (id, expectedRevision, content) => {
+		if ((await read(id)).revision !== expectedRevision) throw new Error("Studio source changed elsewhere. Reopen it before saving.");
+		return persist({
+			...content,
+			id,
+			revision: expectedRevision + 1
+		});
+	};
+	if (kind === "instance") repository.transaction = (operation) => withLock(() => operation({
+		read,
+		list: repository.list,
+		create: createUnlocked,
+		replace: replaceUnlocked,
+		retainTree: (entries) => retainEntriesUnlocked(checkEntries(entries)),
+		async trash(id, expectedRevision) {
+			const current = await read(id);
+			if (current.revision !== expectedRevision) throw new Error("Studio source changed elsewhere. Reopen it before deleting.");
+			const file = draftPath(id);
+			await moveToTrash(file);
+			try {
+				await lstat(file);
+				throw new Error("The system trash did not move this Studio working copy.");
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+			}
+			return {
+				id,
+				revision: current.revision,
+				trashed: true
+			};
+		},
+		async migrate(id, expectedRevision, content) {
+			const current = await read(id);
+			if (current.revision !== expectedRevision || current.recordVersion === 2) throw new Error("Legacy instance changed or was already migrated.");
+			const backup = join(root, `${id}.legacy-v1.json`);
+			const original = JSON.stringify({
+				format,
+				...current
+			});
+			try {
+				if (await readRegular(backup, MAX_DOCUMENT_BYTES) !== original) throw new Error("Existing legacy recovery backup differs from the current record.");
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+				await writeAtomic(backup, original);
+			}
+			return replaceUnlocked(id, expectedRevision, content);
+		}
+	}));
+	const openSnapshot = async (id) => {
+		if (typeof id !== "string" || !HASH.test(id)) throw new Error("Invalid Studio source snapshot.");
+		const text = await readRegular(join(snapshots, `${id}.json`), MAX_SOURCE_BYTES * 2);
+		if (hash(text) !== id) throw new Error("Studio source snapshot integrity check failed.");
+		const document = JSON.parse(text);
+		const closure = Array.isArray(document) ? void 0 : document;
+		if (closure && closure.format !== "studio-source-closure/v1") throw new Error("Invalid Studio source closure.");
+		const entries = closure ? closure.entries : document;
+		const files = new Map(entries);
+		const virtualRoot = resolve(root, "virtual-source", id);
+		const keyOf = (path) => {
+			const absolute = resolve(path);
+			if (!inside(virtualRoot, absolute)) throw new Error("Preview path escapes its source snapshot.");
+			return relative(virtualRoot, absolute).split(sep).join("/");
+		};
+		const children = (path) => {
+			const key = keyOf(path), prefix = key ? `${key}/` : "";
+			return [...new Set([...files.keys()].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length).split("/")[0]))].sort();
+		};
+		const snapshotRoot = closure ? resolve(virtualRoot, closure.kitPath) : virtualRoot;
+		keyOf(snapshotRoot);
+		const loadOptions = closure ? {
+			sourceId: closure.sourceId,
+			bundles: closure.bundles.map((bundle) => {
+				const rootDir = resolve(virtualRoot, bundle.path);
+				keyOf(rootDir);
+				return {
+					name: bundle.name,
+					version: bundle.version,
+					sourceId: bundle.sourceId,
+					rootDir
+				};
+			})
+		} : void 0;
+		return {
+			id,
+			root: snapshotRoot,
+			storageRoot: virtualRoot,
+			...loadOptions ? { loadOptions } : {},
+			fs: {
+				async readBytes(path) {
+					const bytes = files.get(keyOf(path));
+					return bytes === void 0 ? void 0 : Buffer.from(bytes, "base64");
+				},
+				async readText(path) {
+					const bytes = files.get(keyOf(path));
+					return bytes === void 0 ? void 0 : new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(bytes, "base64"));
+				},
+				async readResource(path) {
+					const bytes = files.get(keyOf(path));
+					return bytes === void 0 ? void 0 : readStudioArchiveResource(path, Buffer.from(bytes, "base64"));
+				},
+				async listDir(path) {
+					return children(path);
+				},
+				async isDirectory(path) {
+					return children(path).length > 0;
+				},
+				async realPath(path) {
+					keyOf(path);
+					return resolve(path);
+				}
+			}
+		};
+	};
+	const checkEntries = (entries) => {
+		if (!Array.isArray(entries) || entries.length > 4096) throw new Error("Source tree exceeds 4096 files.");
+		const seen = /* @__PURE__ */ new Set();
+		let bytes = 0;
+		return entries.map((entry) => {
+			const { path, base64 } = entry ?? {};
+			if (typeof path !== "string" || !path || path.length > 1024 || /[\\:\u0000-\u001f\u007f]/u.test(path) || path.split("/").some((part) => !part || [
+				".",
+				"..",
+				".git",
+				"node_modules"
+			].includes(part)) || seen.has(path) || typeof base64 !== "string" || Buffer.from(base64, "base64").toString("base64") !== base64) throw new Error("Invalid source tree entry.");
+			seen.add(path);
+			bytes += Buffer.byteLength(base64, "base64");
+			if (bytes > MAX_SOURCE_BYTES) throw new Error("Source tree exceeds 16 MiB.");
+			return [path, base64];
+		}).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+	};
+	const retainEntriesUnlocked = async (entries, closure) => {
+		const text = JSON.stringify(closure ? {
+			...closure,
+			entries
+		} : entries), id = hash(text), destination = join(snapshots, `${id}.json`);
+		try {
+			if (hash(await readRegular(destination, MAX_SOURCE_BYTES * 2)) !== id) throw new Error("Studio snapshot content mismatch.");
+			return openSnapshot(id);
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		await writeAtomic(destination, text);
+		return openSnapshot(id);
+	};
+	const retainEntries = (entries, closure) => withLock(() => retainEntriesUnlocked(entries, closure));
+	const sources = {
+		open: openSnapshot,
+		...kind === "instance" ? { retainTree: (entries) => withLock(() => retainEntriesUnlocked(checkEntries(entries))) } : {},
+		async capture(pin) {
+			if (!kitRootReal || typeof readInstalledKit !== "function") throw new Error("Installed Kit capture is not configured for this storage port.");
+			const installed = await readInstalledKit();
+			if (pin.name !== installed.name) throw new Error("Select the current installed Kit identity.");
+			const entries = [], ignored = /* @__PURE__ */ new Set([".git", "node_modules"]);
+			let total = 0, nodes = 0;
+			const walk = async (directory, base, prefix) => {
+				if (++nodes > 8192 || relative(base, directory).split(sep).length > 32) throw new Error("Studio source tree exceeds directory limits.");
+				for (const name of (await readdir(directory)).sort()) {
+					if (ignored.has(name)) continue;
+					const file = join(directory, name), info = await lstat(file);
+					if (info.isSymbolicLink()) throw new Error("Studio cannot snapshot source symlinks.");
+					if (info.isDirectory()) await walk(file, base, prefix);
+					else if (info.isFile()) {
+						if (total + info.size > MAX_SOURCE_BYTES || entries.length >= 4096) throw new Error("Kit preview snapshot exceeds 16 MiB or 4096 files.");
+						const bytes = await readFile(file);
+						total += bytes.length;
+						if (total > MAX_SOURCE_BYTES) throw new Error("Kit preview snapshot exceeds 16 MiB.");
+						entries.push([prefix + relative(base, file).split(sep).join("/"), bytes.toString("base64")]);
+					} else throw new Error("Studio sources must be regular files or directories.");
+				}
+			};
+			const sourceRoot = resolve(installed.sourceRoot ?? kitRootReal);
+			if (await realpath(sourceRoot) !== sourceRoot) throw new Error("Studio cannot snapshot source symlinks.");
+			if (await readFile(join(sourceRoot, "kit.yaml"), "utf8").catch((error) => {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}) === void 0) {
+				await walk(sourceRoot, sourceRoot, "");
+				return retainEntries(entries);
+			}
+			if (!Array.isArray(installed.skills)) throw new Error("Independent capture requires compiled mounted Bundles.");
+			const kitPath = `kits/${installed.name}`, bundles = [];
+			await walk(sourceRoot, sourceRoot, `${kitPath}/`);
+			for (const skill of installed.skills) {
+				const pin = {
+					name: skill.catalogName ?? skill.name,
+					version: String(skill.version)
+				};
+				const retained = await readInstalledBundle?.(pin);
+				const bundleRoot = resolve(retained?.resourceRoot ?? skill.resourceRoot ?? "");
+				if (!retained?.resourceRoot && !skill.resourceRoot) throw new Error("Mounted Bundle source root is missing.");
+				if (await realpath(bundleRoot) !== bundleRoot) throw new Error("Studio cannot snapshot source symlinks.");
+				const path = `bundles/${pin.name}`;
+				await walk(bundleRoot, bundleRoot, `${path}/`);
+				bundles.push({
+					...pin,
+					path,
+					sourceId: retained?.sourceId ?? "companion:explicit-kit"
+				});
+			}
+			const checked = checkEntries(entries.map(([path, base64]) => ({
+				path,
+				base64
+			})));
+			return retainEntries(checked, {
+				format: "studio-source-closure/v1",
+				kitPath,
+				sourceId: "companion:explicit-kit",
+				bundles
+			});
+		}
+	};
+	return {
+		repository: kind === "panel" ? {
+			read,
+			list: repository.list
+		} : repository,
+		sources
+	};
+}
+//#endregion
+//#region src/node/studio-instances.mjs
+/** Independent local Studio sources; composition and identity rewriting belong to Core adapters. */
+/** Byte-complete virtual snapshot over canonical retained S2 files; no filesystem extraction. */
+function archiveSnapshot(root, entries, sourceId) {
+	const files = new Map(entries.map((entry) => [entry.path, Buffer.from(entry.base64, "base64")]));
+	const key = (path) => {
+		const value = relative(root, resolve(path));
+		if (isAbsolute(value) || value === ".." || value.startsWith(`..${sep}`)) throw new Error("Instance archive read escaped its retained tree.");
+		return value.split(sep).join("/");
+	};
+	const children = (path) => {
+		const selected = key(path), prefix = selected ? selected + "/" : "";
+		return [...new Set([...files.keys()].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length).split("/")[0]))].sort();
+	};
+	return {
+		root,
+		sourceId,
+		listFiles: async () => [...files.keys()],
+		readBytes: async (path) => {
+			const bytes = files.get(key(path));
+			if (!bytes) throw new Error("Missing retained instance archive file.");
+			return Buffer.from(bytes);
+		},
+		fs: {
+			readText: async (path) => {
+				const bytes = files.get(key(path));
+				return bytes === void 0 ? void 0 : new TextDecoder("utf8", { fatal: true }).decode(bytes);
+			},
+			readResource: async (path) => {
+				const bytes = files.get(key(path));
+				return bytes === void 0 ? void 0 : readStudioArchiveResource(path, bytes);
+			},
+			listDir: async (path) => children(path),
+			isDirectory: async (path) => children(path).length > 0,
+			realPath: async (path) => {
+				key(path);
+				return resolve(path);
+			}
+		}
+	};
+}
+/**
+* @typedef {{path:string,base64:string}} Entry
+* @typedef {{name:string,version:string}} Pin
+* @typedef {{zh:string,en:string}} Title
+* @typedef {{snapshot:string,sourceId:string}} SourceRef
+* @typedef {{bindingKey:string,bundle:Pin & {source:SourceRef,instanceId?:string,revision?:number}}} Mount
+* Required trusted ports (never browser parameters):
+* catalog.listBundles(): Promise<Array<Pin & {title:Title,runtimeName:string}>>
+* catalog.captureKit(pin): Promise<{files:Entry[],title?:Title,mounts:Array<Pin & {bindingKey:string}>}>
+* catalog.captureBundle(pin): Promise<{files:Entry[],title:Title,sourceId:string,runtimeName:string}>
+* composition.forkBundle({files:Entry[],from:Pin,to:Pin,runtimeName:string}): Promise<Entry[]>
+* composition.projectMounts({kit:Pin,kitFiles:Entry[],mounts:Array<Pin & {bindingKey:string}>,resolveBundle(pin)}): Promise<Entry[]>
+* composition.validateKit({kit:Pin,kitFiles:Entry[],mounts:Mount[],resolveBundle(pin)}): Promise<void>
+* resolveBundle returns {files:Entry[],sourceId:string} for retained exact pins only.
+* Optional composition.preview returns the existing StudioPanelPreviewResult:
+* Kit input adds {kind:'kit',bundle,revision,sampleSource} to validateKit input.
+* Bundle input: {kind:'bundle',bundle,runtimeName,bundleFiles,sourceId,revision,sampleSource}.
+* projectMounts owns kit.yaml AND generated XML. forkBundle changes ONLY skill.yaml identity;
+* runtime name, SKILL frontmatter/body and validation paths remain byte-identical.
+*/
+const MAX_TEXT = 1048576;
+const pin = (value) => {
+	if (!value || typeof value.name !== "string" || !/^[a-z][a-z0-9_]*$/.test(value.name) || typeof value.version !== "string" || !/^\d+\.\d+$/.test(value.version)) throw new Error("Select an exact source version.");
+	return {
+		name: value.name,
+		version: value.version
+	};
+};
+const same = (a, b) => a.name === b.name;
+const runtimeNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+const runtimeNameOf = (value) => {
+	if (typeof value !== "string" || !runtimeNamePattern.test(value)) throw new Error("Trusted Bundle runtime name is missing or invalid.");
+	return value;
+};
+const titleOf = (value) => {
+	if (!value || typeof value.zh !== "string" || typeof value.en !== "string" || !value.zh.trim() || !value.en.trim() || value.zh.length > 200 || value.en.length > 200) throw new Error("Provide Chinese and English display names of at most 200 characters.");
+	return {
+		zh: value.zh.trim(),
+		en: value.en.trim()
+	};
+};
+const safePath = (path) => {
+	if (typeof path !== "string" || !path || path.length > 1024 || /[\\:\u0000-\u001f\u007f]/u.test(path) || path.split("/").some((part) => !part || [
+		".",
+		"..",
+		".git",
+		"node_modules",
+		"__proto__",
+		"constructor",
+		"prototype"
+	].includes(part))) throw new Error("Invalid instance source path.");
+	return path;
+};
+const checkRevision = (record, expected) => {
+	if (!Number.isSafeInteger(expected) || record.revision !== expected) throw new Error("Instance changed elsewhere. Reopen it before saving.");
+};
+const active = (record) => {
+	if (record.deletedAt) throw new Error("This working copy is no longer available or has been moved to the system trash.");
+	return record;
+};
+const modern = (record) => {
+	active(record);
+	if (record.recordVersion !== 2) throw new Error("This legacy instance requires explicit migration before editing or mounting.");
+	return record;
+};
+const decode$1 = (base64) => {
+	const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(base64, "base64"));
+	if (text.includes("\0")) throw new Error("Binary source files cannot be edited as text.");
+	return text;
+};
+const localPin = (kind, version, id = randomUUID()) => ({
+	name: `local_${kind}_${id.replaceAll("-", "_")}`,
+	version
+});
+const localSourceId = (kind, identity) => `local:${kind}:${identity.name}`;
+const requireSourceId = (value) => {
+	if (typeof value !== "string" || !value || value.length > 4096 || /[\u0000-\u001f\u007f]/u.test(value)) throw new Error("Trusted source identity is missing or invalid.");
+	return value;
+};
+const canonicalFiles = (files) => JSON.stringify(files.map(({ path, base64 }) => [path, base64]).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+function blankSources(kind, identity, title) {
+	const entry = (path, content) => ({
+		path,
+		base64: Buffer.from(content, "utf8").toString("base64")
+	});
+	const frontmatter = stringify({
+		...identity,
+		description: kind === "kit" ? "A new Design Kit being authored." : "A new design Bundle being authored."
+	});
+	if (kind === "kit") return [entry("mindset.md", "---\n" + frontmatter + "---\n\n# " + title.en + "\n\nDefine this Kit’s design purpose, domain judgment and Bundle selection guidance.\n\n<design_skills>\n</design_skills>\n"), entry("kit.yaml", stringify({
+		version: 1,
+		mounts: []
+	}))];
+	return [
+		entry("SKILL.md", "---\n" + frontmatter + "---\n\n# " + title.en + "\n\nThis is an unfinished authoring source. Define the user need, owned design facts, domain methods, failure handling and revision protocol before using this Bundle.\n\nKeep the [output contract](reference/output-contract.md), schema, validation and Panel aligned.\n"),
+		entry("skill.yaml", stringify({
+			...identity,
+			title,
+			label: { ...title },
+			execution: { handoff: "must_edit" },
+			presentation: { mode: "declarative" }
+		})),
+		entry("schema.yaml", "# Define the domain-owned design facts before use.\ntype: object\nadditional_properties: false\nproperties: {}\n"),
+		entry("validation.yaml", stringify({
+			skill: identity.name,
+			rules: []
+		})),
+		entry("panel.yaml", "# Compose the shared components after defining the design facts.\nversion: 1\nsections: []\nfields: []\n"),
+		entry("reference/output-contract.md", "# Output contract\n\nThis Bundle is not yet defined. Specify owned facts, source evidence, validation and saved outputs alongside the method.\n"),
+		entry("reference/preview.json", "{}\n")
+	];
+}
+async function createStudioInstances(options) {
+	const { catalog, composition, stateRoot } = options;
+	if (!catalog || ![
+		"listBundles",
+		"captureKit",
+		"captureBundle"
+	].every((method) => typeof catalog[method] === "function") || !composition || ![
+		"forkBundle",
+		"projectMounts",
+		"validateKit"
+	].every((method) => typeof composition[method] === "function")) throw new Error("Independent Studio catalog and Core composition ports are required.");
+	const { repository, sources } = await createStudioDraftPorts(options, "instance");
+	const entriesOf = async (snapshotId) => {
+		const snapshot = await sources.open(snapshotId), entries = [];
+		const walk = async (prefix) => {
+			for (const name of await snapshot.fs.listDir(join(snapshot.root, prefix))) {
+				const path = prefix ? `${prefix}/${name}` : name;
+				if (await snapshot.fs.isDirectory(join(snapshot.root, path))) await walk(path);
+				else entries.push({
+					path,
+					base64: (await snapshot.fs.readBytes(join(snapshot.root, path))).toString("base64")
+				});
+			}
+		};
+		await walk("");
+		return entries;
+	};
+	const filesOf = async (record) => {
+		const files = new Map((await entriesOf(record.baseSnapshot)).map((entry) => [entry.path, entry.base64]));
+		for (const [path, content] of Object.entries(record.overlays)) files.set(path, Buffer.from(content).toString("base64"));
+		return [...files].map(([path, base64]) => ({
+			path,
+			base64
+		}));
+	};
+	const references = (record, records) => records.filter((item) => !item.deletedAt && item.kind === "kit" && item.mounts.some((mount) => (mount.bundle.instanceId ?? mount.instanceId) === record.id || record.current === true && record.kind === "bundle" && mount.bundle.name === record.bundle.name)).map(({ id, title }) => ({
+		id,
+		title
+	}));
+	const projection = (record, records) => {
+		const { overlays: _overlays, importedFromSnapshot: _imported, ...result } = record;
+		return {
+			...result,
+			refs: references(record, records),
+			...record.recordVersion !== 2 ? { requiresMigration: true } : {}
+		};
+	};
+	const displayCopy = async (record) => {
+		if (record.recordVersion !== 2) return {};
+		const snapshot = await sources.open(record.baseSnapshot);
+		const text = async (path) => {
+			safePath(path);
+			let value;
+			try {
+				value = record.overlays[path] ?? await snapshot.fs.readText(join(snapshot.root, path));
+			} catch (error) {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}
+			return typeof value === "string" && Buffer.byteLength(value) <= MAX_TEXT ? value : void 0;
+		};
+		const source = await text(record.kind === "kit" ? "mindset.md" : "SKILL.md");
+		const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source ?? "");
+		let meta = {}, translated;
+		try {
+			meta = frontmatter ? parse(frontmatter[1]) ?? {} : {};
+		} catch {}
+		if (record.kind === "kit") translated = meta.display_description;
+		else {
+			let locales = {};
+			try {
+				locales = parse(await text("panel.yaml") ?? "")?.i18n?.locales ?? {};
+			} catch {}
+			const readLocale = async (locale) => {
+				const path = locales[locale];
+				if (typeof path !== "string" || !/^locales\/[A-Za-z0-9._-]+\.json$/.test(path)) return void 0;
+				try {
+					return JSON.parse(await text(path) ?? "{}").bundleDescription;
+				} catch {
+					return;
+				}
+			};
+			translated = {
+				zh: await readLocale("zh-CN"),
+				en: await readLocale("en-US")
+			};
+			if (translated.zh === void 0 && translated.en === void 0) try {
+				translated = parse(await text("skill.yaml") ?? "")?.description;
+			} catch {}
+		}
+		return {
+			...typeof meta.description === "string" ? { description: meta.description } : {},
+			...translated && ["zh", "en"].every((language) => typeof translated[language] === "string" && translated[language].trim()) ? { displayDescription: {
+				zh: translated.zh,
+				en: translated.en
+			} } : {}
+		};
+	};
+	const candidates = async (records) => {
+		const result = [...(await catalog.listBundles().catch(() => [])).map((item) => ({
+			...pin(item),
+			title: titleOf(item.title),
+			runtimeName: runtimeNameOf(item.runtimeName),
+			...typeof item.description === "string" ? { description: item.description } : {},
+			...item.displayDescription && ["zh", "en"].every((language) => typeof item.displayDescription[language] === "string" && item.displayDescription[language].trim()) ? { displayDescription: {
+				zh: item.displayDescription.zh,
+				en: item.displayDescription.en
+			} } : {}
+		})), ...await Promise.all(records.filter((item) => item.recordVersion === 2 && item.kind === "bundle" && !item.deletedAt).map(async (item) => ({
+			...pin(item.bundle),
+			title: item.title,
+			runtimeName: runtimeNameOf(item.runtimeName),
+			instanceId: item.id,
+			revision: item.revision,
+			...await displayCopy(item)
+		})))];
+		const unique = /* @__PURE__ */ new Map();
+		for (const item of result) if (!unique.get(item.name) || item.instanceId !== void 0) unique.set(item.name, item);
+		return [...unique.values()];
+	};
+	const identityDiagnostics = (record, files) => {
+		if (record.kind !== "bundle") return [];
+		const file = files.find((file) => file.path === "skill.yaml");
+		if (!file) return [];
+		let manifest;
+		try {
+			manifest = parse(decode$1(file.base64));
+		} catch {
+			return [];
+		}
+		if ((manifest?.identity ?? manifest?.name) === record.bundle.name) return [];
+		return [{
+			code: "instance.identity",
+			subject: "skill.yaml",
+			message: `skill.yaml：请设置 identity: ${record.bundle.name}；name 与 SKILL.md 的运行名称保持一致。\nSet skill.yaml identity to ${record.bundle.name}. Keep name consistent with the runtime name in SKILL.md.`
+		}];
+	};
+	const displayDiagnostics = (record, diagnostics) => diagnostics.map((diagnostic) => {
+		if (record.kind !== "kit") return diagnostic;
+		if (/Mindset .*?(?:must contain|has an empty).*?<design_skills> catalog/.test(diagnostic.message)) return {
+			...diagnostic,
+			subject: "mindset.md",
+			message: "mindset.md 的技能目录尚未完善：请保留方法正文，并按 kit.yaml 中的挂载补充一个 <design_skills> 目录。\nComplete one <design_skills> catalog in mindset.md using the mounts in kit.yaml, while preserving the method guidance."
+		};
+		return {
+			...diagnostic,
+			message: diagnostic.message.replaceAll(record.kit.name, `${record.title.zh} / ${record.title.en}`)
+		};
+	});
+	const readinessDiagnostics = (record, diagnostics) => displayDiagnostics(record, diagnostics).map(({ subject, ...diagnostic }) => ({
+		...diagnostic,
+		...subject ? { path: subject } : {}
+	}));
+	const readiness = async (record) => {
+		if (!record.importedFromSnapshot) return {};
+		const files = await filesOf(record), paths = new Set(files.map((file) => file.path)), diagnostics = [];
+		const required = record.kind === "bundle" ? [
+			"SKILL.md",
+			"skill.yaml",
+			"schema.yaml",
+			"validation.yaml"
+		] : ["mindset.md", "kit.yaml"];
+		for (const path of required) if (!paths.has(path)) diagnostics.push({
+			code: "instance.missing_source",
+			path,
+			message: `Missing ${path}. Add this source file to complete the definition.`,
+			severity: "error"
+		});
+		if (!diagnostics.length) try {
+			if (record.kind === "kit") {
+				for (const mount of record.mounts) if (!(await resolveMounts(record.mounts, record.current === true)(mount.bundle)).files.some((file) => file.path === "SKILL.md")) diagnostics.push({
+					code: "instance.missing_mount",
+					path: "kit.yaml",
+					message: `Missing exact Bundle ${mount.bundle.name}@${mount.bundle.version}. Repair the Bundle selection in mount management.`,
+					severity: "error"
+				});
+				if (!diagnostics.length) await composition.validateKit(await kitInput(record));
+			} else {
+				const identity = identityDiagnostics(record, files);
+				if (identity.length) return { readiness: {
+					ready: false,
+					diagnostics: readinessDiagnostics(record, identity)
+				} };
+				if (typeof composition.validateBundle !== "function") throw new Error("The host has not supplied the Core Bundle definition validator.");
+				await composition.validateBundle({
+					bundle: record.bundle,
+					bundleFiles: files,
+					sourceId: record.sourceId,
+					runtimeName: record.runtimeName
+				});
+			}
+		} catch (error) {
+			diagnostics.push({
+				code: "instance.definition",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error"
+			});
+		}
+		return { readiness: {
+			ready: diagnostics.length === 0,
+			diagnostics: readinessDiagnostics(record, diagnostics)
+		} };
+	};
+	const importedRuntime = (record, files) => {
+		if (record.kind !== "bundle" || !record.importedFromSnapshot) return {};
+		try {
+			const method = decode$1(files.find((file) => file.path === "SKILL.md")?.base64 ?? "");
+			const metadata = parse(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(method)?.[1] ?? "");
+			return { runtimeName: runtimeNameOf(metadata?.name) };
+		} catch {
+			return {};
+		}
+	};
+	const projectImported = async (record, files) => typeof composition.projectSourceIdentity === "function" ? composition.projectSourceIdentity({
+		kind: record.kind,
+		files,
+		identity: record[record.kind]
+	}) : files;
+	const describe = async (record, records = void 0) => {
+		records ??= await repository.list();
+		if (record.recordVersion !== 2) return projection(record, records);
+		const files = (await filesOf(record)).map((entry) => {
+			const bytes = Buffer.byteLength(entry.base64, "base64");
+			let editable = bytes <= MAX_TEXT;
+			try {
+				decode$1(entry.base64);
+			} catch {
+				editable = false;
+			}
+			return {
+				path: entry.path,
+				bytes,
+				editable
+			};
+		}).sort((a, b) => a.path.localeCompare(b.path));
+		return {
+			...projection(record, records),
+			...await displayCopy(record),
+			...await readiness(record),
+			files,
+			...record.kind === "kit" ? { availableBundles: await candidates(records) } : {}
+		};
+	};
+	const read = async (input) => describe(active(await repository.read(typeof input === "string" ? input : input.id)));
+	const mountRequests = (kitFiles, mounts) => {
+		const declaration = kitFiles.find((file) => file.path === "kit.yaml");
+		try {
+			return declaration ? parseKitMounts(decode$1(declaration.base64)) : mounts.map((mount) => pin(mount.bundle));
+		} catch {
+			return mounts.map((mount) => pin(mount.bundle));
+		}
+	};
+	const resolveMounts = (mounts, currentLibrary = false) => async (requested) => {
+		const selected = mounts.find((mount) => same(mount.bundle, pin(requested)));
+		if (!selected) throw new Error("Core requested a Bundle outside the selected exact mounts.");
+		if (selected.bundle.instanceId) {
+			const current = modern(await repository.read(selected.bundle.instanceId));
+			if (current.kind !== "bundle" || current.bundle.name !== selected.bundle.name) throw new Error("Mounted Bundle identity changed.");
+			return {
+				files: await filesOf(current),
+				sourceId: current.sourceId
+			};
+		}
+		const current = (await repository.list()).find((record) => !record.deletedAt && record.current === true && record.kind === "bundle" && record.bundle.name === selected.bundle.name);
+		if (current) return {
+			files: await filesOf(current),
+			sourceId: current.sourceId
+		};
+		if (currentLibrary && selected.bundle.version !== requested.version) return catalog.captureBundle(pin(requested));
+		return {
+			files: await entriesOf(selected.bundle.source.snapshot),
+			sourceId: selected.bundle.source.sourceId
+		};
+	};
+	const kitInput = async (record) => ({
+		kit: record.kit,
+		kitFiles: await filesOf(record),
+		mounts: record.mounts,
+		resolveBundle: resolveMounts(record.mounts, record.current === true)
+	});
+	const retain = async (tx, files, sourceId) => {
+		requireSourceId(sourceId);
+		return {
+			snapshot: (await tx.retainTree(files)).id,
+			sourceId
+		};
+	};
+	const mountOne = async (tx, requested, available) => {
+		const selected = available.find((item) => same(item, pin(requested)));
+		if (!selected) throw new Error(`Bundle ${requested.name}@${requested.version} is unavailable in the global catalog.`);
+		const bindingKey = runtimeNameOf(requested.bindingKey ?? selected.runtimeName);
+		if (bindingKey !== selected.runtimeName) throw new Error("Bundle binding key must preserve its runtime name.");
+		if (selected.instanceId) {
+			if (requested.instanceId !== void 0 && requested.instanceId !== selected.instanceId) throw new Error("Bundle instance identity does not match its pin.");
+			const record = modern(await tx.read(selected.instanceId));
+			return {
+				bindingKey,
+				bundle: {
+					...record.bundle,
+					instanceId: record.id,
+					revision: record.revision,
+					source: await retain(tx, await filesOf(record), record.sourceId)
+				}
+			};
+		}
+		if (requested.instanceId !== void 0 || requested.revision !== void 0) throw new Error("Installed Bundle pins do not accept local instance fields.");
+		const captured = await catalog.captureBundle(pin(requested));
+		return {
+			bindingKey,
+			bundle: {
+				...pin(requested),
+				source: await retain(tx, captured.files, captured.sourceId)
+			}
+		};
+	};
+	const projectedKit = async (record, mounts) => {
+		const kitFiles = await composition.projectMounts({
+			allowEmptyDraft: true,
+			kit: record.kit,
+			kitFiles: await filesOf(record),
+			mounts: mounts.map((mount) => ({
+				bindingKey: mount.bindingKey,
+				...pin(mount.bundle)
+			})),
+			resolveBundle: resolveMounts(mounts, record.current === true)
+		});
+		if (kitFiles.some((entry) => entry.path.startsWith("skills/"))) throw new Error("Kit-owned sources cannot contain copied Bundle trees.");
+		return kitFiles;
+	};
+	const newTitle = (input, base) => titleOf(input ?? {
+		zh: `${base.zh} 副本`,
+		en: `${base.en} copy`
+	});
+	const prepareFiles = async (current, input) => {
+		const before = await filesOf(current), entries = new Map(before.map((file) => [file.path, file.base64])), diff = [];
+		let diffBytes = 0;
+		for (const { path, content } of input.changes) {
+			const original = entries.get(path);
+			if (original === void 0 && content === null) throw new Error(`Cannot remove missing source file ${path}.`);
+			if (original !== void 0 && Buffer.byteLength(original, "base64") > MAX_TEXT) throw new Error("Text editing is limited to 1 MiB per existing file.");
+			const previous = original === void 0 ? void 0 : decode$1(original);
+			diffBytes += Buffer.byteLength(previous ?? "") + Buffer.byteLength(content ?? "");
+			if (diffBytes > STUDIO_INSTANCE_CHANGE_LIMITS.diffBytes) throw new Error("Instance diff exceeds the 8 MiB text budget.");
+			if (current.kind === "kit" && (path === "kit.yaml" || path.startsWith("skills/"))) throw new Error("Use Bundle mount management to edit the Kit declaration; Kit copies contain only Kit-owned files.");
+			if (content === null) entries.delete(path);
+			else entries.set(path, Buffer.from(content, "utf8").toString("base64"));
+			if (previous !== (content ?? void 0)) diff.push({
+				path,
+				...previous === void 0 ? {} : { before: previous },
+				...content === null ? {} : { after: content }
+			});
+		}
+		const files = [...entries].map(([path, base64]) => ({
+			path,
+			base64
+		}));
+		if (files.length > 4096 || files.reduce((bytes, file) => bytes + Buffer.byteLength(file.base64, "base64"), 0) > 16777216) throw new Error("Instance source tree exceeds 4096 files or 16 MiB.");
+		const paths = new Set(entries.keys());
+		for (const path of paths) {
+			const parts = path.split("/");
+			for (let length = 1; length < parts.length; length++) if (paths.has(parts.slice(0, length).join("/"))) throw new Error("Instance source file conflicts with a directory.");
+		}
+		const dependencyRequests = current.kind === "kit" ? mountRequests(files, current.mounts) : [];
+		const digest = createHash("sha256").update(JSON.stringify({
+			id: current.id,
+			baseRevision: current.revision,
+			kind: current.kind,
+			pin: current[current.kind],
+			runtimeName: current.runtimeName,
+			sourceId: current.sourceId,
+			mounts: await Promise.all(dependencyRequests.map(async (requested) => ({
+				name: requested.name,
+				source: await resolveMounts(current.mounts, current.current === true)(requested)
+			}))),
+			before: canonicalFiles(before),
+			after: canonicalFiles(files),
+			bundle: input.bundle,
+			sampleSource: input.sampleSource
+		})).digest("hex");
+		return {
+			files,
+			diff: diff.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+			digest
+		};
+	};
+	const previewChanges = async (current, input, prepared) => {
+		const revision = current.revision + 1;
+		let result;
+		try {
+			if (typeof composition.preview !== "function") throw new Error("The host has not supplied the Core preview adapter.");
+			if (current.kind === "bundle") {
+				if (input.bundle && !same(input.bundle, current.bundle)) throw new Error("Select this exact Bundle instance.");
+				const identity = identityDiagnostics(current, prepared.files);
+				result = identity.length ? { diagnostics: identity } : await composition.preview({
+					kind: "bundle",
+					bundle: current.bundle,
+					runtimeName: importedRuntime(current, prepared.files).runtimeName ?? current.runtimeName,
+					bundleFiles: prepared.files,
+					sourceId: current.sourceId,
+					revision,
+					sampleSource: input.sampleSource
+				});
+			} else {
+				const bundle = pin(input.bundle);
+				if (!current.mounts.some((mount) => same(mount.bundle, bundle))) throw new Error("Select an exact mounted Bundle.");
+				result = await composition.preview({
+					kind: "kit",
+					kit: current.kit,
+					kitFiles: prepared.files,
+					mounts: current.mounts,
+					resolveBundle: resolveMounts(current.mounts, current.current === true),
+					bundle,
+					revision,
+					sampleSource: input.sampleSource
+				});
+			}
+			if (!result || !Array.isArray(result.diagnostics)) throw new Error("Core preview did not return a diagnostic result.");
+			if (result.preview && result.preview.revision !== revision) throw new Error("Core preview revision does not match this candidate.");
+		} catch (error) {
+			result = { diagnostics: [{
+				code: "instance.candidate",
+				message: error instanceof Error ? error.message : String(error)
+			}] };
+		}
+		return {
+			id: current.id,
+			baseRevision: current.revision,
+			revision,
+			digest: prepared.digest,
+			diff: prepared.diff,
+			valid: !!result.preview && !result.diagnostics.some((entry) => entry.severity !== "warning"),
+			diagnostics: displayDiagnostics(current, result.diagnostics),
+			...result.preview ? { preview: result.preview } : {}
+		};
+	};
+	const definitionOnly = (current, input, files) => {
+		if (current.kind === "kit") return input.bundle === void 0;
+		try {
+			const manifest = parse(decode$1(files.find((file) => file.path === "skill.yaml")?.base64 ?? ""));
+			return manifest && typeof manifest === "object" && !Array.isArray(manifest) && (manifest.presentation === void 0 || manifest.presentation?.mode === "none");
+		} catch {
+			return false;
+		}
+	};
+	const definitionDiagnostics = async (current, input, files) => {
+		const diagnostics = [];
+		try {
+			if (current.kind === "kit") await composition.validateKit({
+				kit: current.kit,
+				kitFiles: files,
+				mounts: current.mounts,
+				resolveBundle: resolveMounts(current.mounts, current.current === true)
+			});
+			else {
+				if (input.bundle && !same(input.bundle, current.bundle)) throw new Error("Select this exact Bundle instance.");
+				diagnostics.push(...identityDiagnostics(current, files));
+				if (!diagnostics.length) {
+					if (typeof composition.validateBundle !== "function") throw new Error("The host has not supplied the Core Bundle definition validator.");
+					await composition.validateBundle({
+						bundle: current.bundle,
+						bundleFiles: files,
+						sourceId: current.sourceId,
+						runtimeName: importedRuntime(current, files).runtimeName ?? current.runtimeName
+					});
+				}
+			}
+		} catch (error) {
+			diagnostics.push({
+				code: "instance.definition",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+		return diagnostics;
+	};
+	const validateChanges = async (current, input, prepared) => {
+		if (!definitionOnly(current, input, prepared.files)) return previewChanges(current, input, prepared);
+		const diagnostics = await definitionDiagnostics(current, input, prepared.files);
+		return {
+			id: current.id,
+			baseRevision: current.revision,
+			revision: current.revision + 1,
+			digest: prepared.digest,
+			diff: prepared.diff,
+			valid: diagnostics.length === 0,
+			diagnostics: displayDiagnostics(current, diagnostics)
+		};
+	};
+	return {
+		read,
+		async captureKit({ id, expectedRevision } = {}) {
+			return repository.transaction(async (tx) => {
+				const record = modern(await tx.read(id));
+				if (expectedRevision !== void 0) checkRevision(record, expectedRevision);
+				if (record.kind !== "kit") throw new Error("Select a Kit source.");
+				const captured = /* @__PURE__ */ new Map(), kitFiles = await filesOf(record), resolveBundle = resolveMounts(record.mounts, record.current === true);
+				for (const requested of mountRequests(kitFiles, record.mounts)) captured.set(requested.name, await resolveBundle(requested));
+				return {
+					kit: record.kit,
+					kitFiles,
+					mounts: structuredClone(record.mounts),
+					resolveBundle: async (requested) => captured.get(requested.name)
+				};
+			});
+		},
+		async loadKit(input) {
+			if (typeof composition.loadKit !== "function") throw new Error("The host has not supplied the Core Kit loader.");
+			return composition.loadKit(await this.captureKit(input));
+		},
+		async editCurrent(input) {
+			if (!["kit", "bundle"].includes(input.kind)) throw new Error("Select a Kit or Bundle.");
+			const selected = pin(input[input.kind]);
+			const record = await repository.transaction(async (tx) => {
+				const records = await tx.list();
+				const existing = records.find((item) => !item.deletedAt && item.kind === input.kind && item.current === true && item[item.kind].name === selected.name);
+				if (existing) return existing;
+				const captured = input.kind === "kit" ? await catalog.captureKit(selected) : await catalog.captureBundle(selected);
+				const sourceId = input.kind === "bundle" ? captured.sourceId : `local:kit:${selected.name}`;
+				const source = await retain(tx, captured.files, sourceId);
+				const mounts = [];
+				if (input.kind === "kit") {
+					const available = await candidates(records);
+					for (const mounted of captured.mounts) mounts.push(await mountOne(tx, mounted, available));
+				}
+				return tx.create({
+					recordVersion: 2,
+					current: true,
+					kind: input.kind,
+					[input.kind]: selected,
+					title: captured.title ?? {
+						zh: selected.name,
+						en: selected.name
+					},
+					source: { [input.kind]: selected },
+					sourceId,
+					baseSnapshot: source.snapshot,
+					overlays: {},
+					mounts,
+					...input.kind === "bundle" ? { runtimeName: captured.runtimeName } : {},
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			});
+			return describe(record);
+		},
+		/** Unsaved, bounded source candidate; diff and real preview use the same bytes. */
+		async exportArchive(request) {
+			const input = structuredClone(request);
+			return repository.transaction(async (tx) => {
+				const current = active(await tx.read(input.id));
+				if (current.revision !== input.expectedRevision) throw new Error("Instance revision changed before archive export.");
+				if (current.recordVersion !== 2) throw new Error("Migrate the working copy before archive export.");
+				const root = resolve(stateRoot, "instance-archive-view", current.id);
+				const snapshot = archiveSnapshot(root, await filesOf(current), `studio-instance:${current.id}`);
+				if (current.kind === "bundle") snapshot.bundle = pin(current.bundle);
+				else {
+					snapshot.bundles = [];
+					const resolveBundle = resolveMounts(current.mounts, current.current === true);
+					for (const requested of mountRequests(await filesOf(current), current.mounts)) {
+						const captured = await resolveBundle(requested);
+						snapshot.bundles.push({
+							...pin(requested),
+							sourceId: captured.sourceId,
+							snapshot: archiveSnapshot(resolve(root, "..", `${current.id}-bundle-${requested.name}`), captured.files, captured.sourceId)
+						});
+					}
+				}
+				return exportStudioSourceArchive(snapshot, {
+					kind: current.kind,
+					pin: current.kind === "kit" ? current.kit : current.bundle,
+					title: current.title,
+					provenance: input.provenance,
+					...input.dependencies ? { dependencies: input.dependencies } : {}
+				});
+			});
+		},
+		async prepareChanges(request) {
+			const input = normalizeStudioInstanceChanges(request);
+			return repository.transaction(async (tx) => {
+				const current = modern(await tx.read(input.id));
+				checkRevision(current, input.expectedRevision);
+				return validateChanges(current, input, await prepareFiles(current, input));
+			});
+		},
+		/** One snapshot pointer + one existing atomic record CAS, never per-file writes. */
+		async saveChanges(request) {
+			const input = normalizeStudioInstanceChanges(request), mode = request.mode ?? "draft", digest = request.digest;
+			if (!["draft", "validated"].includes(mode)) throw new Error("Select draft or validated save mode.");
+			if ((mode === "validated" || digest !== void 0) && (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest))) throw new Error("Select the exact prepared candidate digest.");
+			let receipt;
+			const record = await repository.transaction(async (tx) => {
+				const current = modern(await tx.read(input.id));
+				checkRevision(current, input.expectedRevision);
+				const prepared = await prepareFiles(current, input);
+				if (digest !== void 0 && digest !== prepared.digest) throw new Error("Candidate source digest changed. Prepare and review the current changes again.");
+				let validation = "not_requested";
+				if (mode === "validated") {
+					const sourceOnly = definitionOnly(current, input, prepared.files);
+					const candidate = await validateChanges(current, input, prepared);
+					if (!candidate.valid) throw new Error(`Candidate failed Core ${sourceOnly ? "definition" : "preview"}: ${candidate.diagnostics.map((entry) => `${entry.code}: ${entry.message}`).join("; ") || "no valid declarative preview"}`);
+					validation = sourceOnly ? "definition_passed" : "preview_passed";
+				}
+				const retained = await retain(tx, prepared.files, current.sourceId);
+				const saved = await tx.replace(current.id, input.expectedRevision, {
+					...current,
+					...importedRuntime(current, prepared.files),
+					baseSnapshot: retained.snapshot,
+					overlays: {}
+				});
+				receipt = {
+					baseRevision: current.revision,
+					revision: saved.revision,
+					digest: prepared.digest,
+					mode,
+					validation
+				};
+				return saved;
+			});
+			return {
+				...await describe(record),
+				changeReceipt: receipt
+			};
+		},
+		async list({ kind } = {}) {
+			if (kind !== void 0 && !["kit", "bundle"].includes(kind)) throw new Error("Unknown instance kind.");
+			const records = await repository.list();
+			return Promise.all(records.filter((record) => !record.deletedAt && (!kind || record.kind === kind)).map(async (record) => ({
+				...projection(record, records),
+				...await displayCopy(record),
+				...await readiness(record)
+			})));
+		},
+		async listBundles() {
+			return candidates(await repository.list());
+		},
+		async importSources(request) {
+			const input = structuredClone(request);
+			if (!input || !["kit", "bundle"].includes(input.kind) || !Array.isArray(input.files)) throw new Error("Provide Kit or Bundle source files.");
+			const kind = input.kind;
+			for (const file of input.files) safePath(file?.path);
+			const paths = new Set(input.files.map((file) => file.path));
+			for (const path of kind === "bundle" ? ["SKILL.md"] : ["mindset.md", "kit.yaml"]) if (!paths.has(path)) throw new Error(`Missing required import source ${path}.`);
+			const metadata = (path) => {
+				try {
+					const text = decode$1(input.files.find((file) => file.path === path)?.base64 ?? "");
+					return parse(path.endsWith(".md") ? /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1] ?? "" : text) ?? {};
+				} catch {
+					return {};
+				}
+			};
+			const method = metadata(kind === "bundle" ? "SKILL.md" : "mindset.md"), manifest = metadata(kind === "bundle" ? "skill.yaml" : "kit.yaml");
+			const version = /^\d+\.\d+$/.test(String(manifest.version)) ? String(manifest.version) : /^\d+\.\d+$/.test(String(method.version)) ? String(method.version) : "1.0";
+			const identity = localPin(kind, version), sourceId = localSourceId(kind, identity);
+			const runtimeName = [method.name, manifest.name].find((value) => typeof value === "string" && runtimeNamePattern.test(value)) ?? identity.name;
+			const label = typeof method.name === "string" && method.name.trim() ? method.name.trim().slice(0, 180) : kind === "kit" ? "Imported Kit" : "Imported Bundle";
+			const inferredTitle = ["zh", "en"].every((language) => typeof manifest.title?.[language] === "string" && manifest.title[language].trim() && manifest.title[language].length <= 200) ? manifest.title : {
+				zh: label,
+				en: label
+			};
+			const baseTitle = titleOf(input.title ?? inferredTitle);
+			const created = await repository.transaction(async (tx) => {
+				const original = await retain(tx, input.files, sourceId);
+				const labels = [...(await tx.list()).filter((record) => !record.deletedAt).map((record) => record.title), ...(await catalog.listBundles()).map((item) => item.title)];
+				let title = baseTitle, suffix = 2;
+				while (labels.some((item) => item.zh === title.zh || item.en === title.en)) {
+					title = titleOf({
+						zh: `${baseTitle.zh.slice(0, 180)} (${suffix})`,
+						en: `${baseTitle.en.slice(0, 180)} (${suffix})`
+					});
+					suffix++;
+				}
+				let files = input.files, mounts = [];
+				if (kind === "kit") {
+					const consumed = /* @__PURE__ */ new Set(), declared = Array.isArray(manifest.mounts) ? manifest.mounts : [];
+					for (const item of declared) {
+						let selected, bindingKey;
+						try {
+							selected = pin(item);
+							bindingKey = runtimeNameOf(item.bindingKey);
+						} catch {
+							continue;
+						}
+						if (mounts.some((mount) => same(mount.bundle, selected) || mount.bindingKey === bindingKey)) continue;
+						const prefix = [
+							`bundles/${selected.name}/${selected.version}/`,
+							`bundles/${selected.name}/`,
+							`skills/${bindingKey}/`
+						].find((prefix) => input.files.some((file) => file.path.startsWith(prefix)));
+						let bundleFiles = prefix ? input.files.filter((file) => file.path.startsWith(prefix)).map((file) => {
+							consumed.add(file.path);
+							return {
+								...file,
+								path: file.path.slice(prefix.length)
+							};
+						}) : [];
+						let mountedSourceId = `import:bundle:${selected.name}@${selected.version}`;
+						if (!prefix) try {
+							const capture = await catalog.captureBundle(selected);
+							bundleFiles = capture.files;
+							mountedSourceId = capture.sourceId;
+						} catch {}
+						mounts.push({
+							bindingKey,
+							bundle: {
+								...selected,
+								source: await retain(tx, bundleFiles, mountedSourceId)
+							}
+						});
+					}
+					files = input.files.filter((file) => !consumed.has(file.path));
+				}
+				const record = {
+					recordVersion: 2,
+					kind,
+					[kind]: identity,
+					title,
+					source: {},
+					sourceId,
+					baseSnapshot: original.snapshot,
+					importedFromSnapshot: original.snapshot,
+					overlays: {},
+					mounts,
+					...kind === "bundle" ? { runtimeName } : {},
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				};
+				files = await projectImported(record, files);
+				record.baseSnapshot = (await retain(tx, files, sourceId)).snapshot;
+				return tx.create(record);
+			});
+			return describe(created);
+		},
+		async create(input) {
+			if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["kind", "title"].includes(key)) || !["kit", "bundle"].includes(input.kind)) throw new Error("Provide a new Kit or Bundle kind and display title.");
+			const kind = input.kind, title = titleOf(input.title), identity = localPin(kind, "1.0");
+			const sourceId = localSourceId(kind, identity), initial = blankSources(kind, identity, title);
+			const files = kind === "kit" ? await composition.projectMounts({
+				allowEmptyDraft: true,
+				kit: identity,
+				kitFiles: initial,
+				mounts: [],
+				resolveBundle: async () => {
+					throw new Error("Blank Kit creation cannot resolve installed Bundles.");
+				}
+			}) : initial;
+			const created = await repository.transaction(async (tx) => {
+				const source = await retain(tx, files, sourceId);
+				return tx.create({
+					recordVersion: 2,
+					kind,
+					[kind]: identity,
+					title,
+					source: {},
+					sourceId,
+					baseSnapshot: source.snapshot,
+					overlays: {},
+					mounts: [],
+					createdBlank: true,
+					...kind === "bundle" ? { runtimeName: identity.name } : {},
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			});
+			return describe(created);
+		},
+		async copy(input) {
+			if (!["kit", "bundle"].includes(input.kind)) throw new Error("Select a Kit or Bundle instance.");
+			const created = await repository.transaction(async (tx) => {
+				const original = input.sourceId ? modern(await tx.read(input.sourceId)) : void 0;
+				if (original && original.kind !== input.kind) throw new Error("The source instance kind does not match.");
+				if (original && input.expectedRevision !== void 0) checkRevision(original, input.expectedRevision);
+				let files, origin, baseTitle, mounts = [], sourcePin, runtimeName;
+				if (original) {
+					files = await filesOf(original);
+					sourcePin = original[original.kind];
+					origin = original.source;
+					baseTitle = original.title;
+					mounts = structuredClone(original.mounts);
+					runtimeName = original.runtimeName;
+				} else if (input.kind === "bundle") {
+					sourcePin = pin(input.bundle);
+					const captured = await catalog.captureBundle(sourcePin);
+					requireSourceId(captured.sourceId);
+					runtimeName = runtimeNameOf(captured.runtimeName);
+					files = captured.files;
+					baseTitle = titleOf(captured.title);
+					origin = { bundle: sourcePin };
+				} else {
+					sourcePin = pin(input.kit);
+					const captured = await catalog.captureKit(sourcePin);
+					files = captured.files;
+					origin = { kit: sourcePin };
+					const label = sourcePin.name.replace(/[_-]+/g, " ");
+					baseTitle = captured.title ?? {
+						zh: label,
+						en: label
+					};
+					const available = await candidates(await tx.list());
+					for (const mounted of captured.mounts) mounts.push(await mountOne(tx, mounted, available));
+				}
+				const identity = localPin(input.kind, sourcePin.version), sourceId = localSourceId(input.kind, identity);
+				if (input.kind === "kit" && files.some((file) => file.path.startsWith("skills/"))) throw new Error("Kit capture must contain only Kit-owned files; legacy whole-Kit sources require explicit migration.");
+				if (input.kind === "bundle") files = original?.importedFromSnapshot ? await projectImported({
+					kind: "bundle",
+					bundle: identity
+				}, files) : await composition.forkBundle({
+					files,
+					from: sourcePin,
+					to: identity,
+					runtimeName
+				});
+				const source = await retain(tx, files, sourceId);
+				const record = {
+					recordVersion: 2,
+					kind: input.kind,
+					[input.kind]: identity,
+					title: newTitle(input.title, baseTitle),
+					source: origin,
+					sourceId,
+					baseSnapshot: source.snapshot,
+					overlays: {},
+					mounts,
+					...input.kind === "bundle" ? { runtimeName } : {},
+					...original?.createdBlank ? { createdBlank: true } : {},
+					...original?.importedFromSnapshot ? { importedFromSnapshot: original.importedFromSnapshot } : {},
+					createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+					...original ? { forkedFrom: {
+						id: original.id,
+						revision: original.revision,
+						pin: sourcePin
+					} } : {}
+				};
+				if (record.kind === "kit") record.baseSnapshot = (await retain(tx, record.importedFromSnapshot ? await projectImported(record, files) : await projectedKit(record, mounts), sourceId)).snapshot;
+				return tx.create(record);
+			});
+			return describe(created);
+		},
+		async rename({ id, expectedRevision, title }) {
+			const nextTitle = titleOf(title);
+			const record = await repository.transaction(async (tx) => {
+				const current = modern(await tx.read(id));
+				checkRevision(current, expectedRevision);
+				return tx.replace(id, expectedRevision, {
+					...current,
+					title: nextTitle
+				});
+			});
+			return describe(record);
+		},
+		async updateMounts({ id, expectedRevision, bundles }) {
+			if (!Array.isArray(bundles) || bundles.length > 4096) throw new Error("Provide a bounded Bundle selection.");
+			if (new Set(bundles.map((item) => pin(item).name)).size !== bundles.length) throw new Error("A Kit can mount each Bundle only once.");
+			const record = await repository.transaction(async (tx) => {
+				const current = modern(await tx.read(id));
+				checkRevision(current, expectedRevision);
+				if (current.kind !== "kit") throw new Error("Mount management requires a local Kit instance.");
+				const available = await candidates(await tx.list()), mounts = [];
+				for (const selected of bundles) {
+					const existing = current.mounts.find((mount) => same(mount.bundle, pin(selected)) && (selected.bindingKey === void 0 || selected.bindingKey === mount.bindingKey) && (selected.instanceId === void 0 || selected.instanceId === mount.bundle.instanceId) && (selected.revision === void 0 || selected.revision === mount.bundle.revision));
+					let mounted = existing;
+					if (existing && current.importedFromSnapshot) {
+						const files = await entriesOf(existing.bundle.source.snapshot);
+						if (available.some((item) => same(item, selected))) {
+							let incomplete = !files.some((file) => file.path === "SKILL.md");
+							if (!incomplete && typeof composition.validateBundle === "function") try {
+								await composition.validateBundle({
+									bundle: pin(existing.bundle),
+									bundleFiles: files,
+									sourceId: existing.bundle.source.sourceId,
+									runtimeName: existing.bindingKey
+								});
+							} catch {
+								incomplete = true;
+							}
+							if (incomplete) try {
+								mounted = await mountOne(tx, selected, available);
+							} catch {}
+						}
+					}
+					mounts.push(mounted ?? await mountOne(tx, selected, available));
+				}
+				if (new Set(mounts.map((mount) => mount.bindingKey)).size !== mounts.length) throw new Error("Bundle binding keys must be unique.");
+				const source = await retain(tx, await projectedKit(current, mounts), current.sourceId);
+				return tx.replace(id, expectedRevision, {
+					...current,
+					mounts,
+					baseSnapshot: source.snapshot,
+					overlays: {}
+				});
+			});
+			return describe(record);
+		},
+		async remove({ id, expectedRevision }) {
+			return repository.transaction(async (tx) => {
+				const current = active(await tx.read(id));
+				checkRevision(current, expectedRevision);
+				const refs = references(current, await tx.list());
+				if (refs.length) throw new Error(`This Bundle is referenced by ${refs.map((item) => item.title.en).join(", ")}. Referenced instances are protected from deletion.`);
+				return tx.trash(id, expectedRevision);
+			});
+		},
+		async readFile({ id, path }) {
+			safePath(path);
+			const record = modern(await repository.read(id)), file = (await filesOf(record)).find((entry) => entry.path === path);
+			if (!file) throw new Error("Instance source file does not exist.");
+			if (Buffer.byteLength(file.base64, "base64") > MAX_TEXT) throw new Error("Text editing is limited to 1 MiB per file.");
+			return {
+				id,
+				revision: record.revision,
+				path,
+				content: decode$1(file.base64)
+			};
+		},
+		async saveFile({ id, expectedRevision, path, content }) {
+			safePath(path);
+			if (typeof content !== "string" || Buffer.byteLength(content) > MAX_TEXT || content.includes("\0")) throw new Error("Source must be UTF-8 text of at most 1 MiB.");
+			const record = await repository.transaction(async (tx) => {
+				const current = modern(await tx.read(id));
+				checkRevision(current, expectedRevision);
+				const files = await filesOf(current), found = files.find((entry) => entry.path === path);
+				if (!found) throw new Error("Select an existing source file to edit.");
+				decode$1(found.base64);
+				if (current.kind === "kit" && path === "kit.yaml") throw new Error("Use Bundle mount management to edit the Kit declaration.");
+				return tx.replace(id, expectedRevision, {
+					...current,
+					...importedRuntime(current, files.map((file) => file.path === path ? {
+						path,
+						base64: Buffer.from(content).toString("base64")
+					} : file)),
+					overlays: {
+						...current.overlays,
+						[path]: content
+					}
+				});
+			});
+			return describe(record);
+		},
+		async preview({ id, expectedRevision, bundle: requested, sampleSource }) {
+			return repository.transaction(async (tx) => {
+				const record = modern(await tx.read(id));
+				checkRevision(record, expectedRevision);
+				const files = record.kind === "bundle" ? await filesOf(record) : void 0;
+				if (files && definitionOnly(record, {}, files)) return { diagnostics: displayDiagnostics(record, await definitionDiagnostics(record, {}, files)) };
+				if (typeof composition.preview !== "function") throw new Error("The host has not supplied the Core preview adapter.");
+				if (record.kind === "bundle") {
+					const diagnostics = identityDiagnostics(record, files);
+					if (diagnostics.length) return { diagnostics };
+					return composition.preview({
+						kind: "bundle",
+						bundle: record.bundle,
+						runtimeName: record.runtimeName,
+						bundleFiles: files,
+						sourceId: record.sourceId,
+						revision: record.revision,
+						sampleSource
+					});
+				}
+				const bundle = pin(requested);
+				if (!record.mounts.some((mount) => same(mount.bundle, bundle))) throw new Error("Select an exact mounted Bundle.");
+				const result = await composition.preview({
+					kind: "kit",
+					...await kitInput(record),
+					bundle,
+					revision: record.revision,
+					sampleSource
+				});
+				return {
+					...result,
+					diagnostics: displayDiagnostics(record, result.diagnostics)
+				};
+			});
+		},
+		async migrate({ id, expectedRevision }) {
+			const migrated = await repository.transaction(async (tx) => {
+				const current = active(await tx.read(id));
+				checkRevision(current, expectedRevision);
+				if (current.recordVersion === 2) throw new Error("Instance is already migrated.");
+				const allFiles = await filesOf(current), identity = localPin(current.kind, current.source[current.kind].version, id), sourceId = localSourceId(current.kind, identity);
+				let files, mounts = [], runtimeName;
+				if (current.kind === "bundle") {
+					const prefix = `${current.bundlePath}/`;
+					files = allFiles.filter((entry) => entry.path.startsWith(prefix)).map((entry) => ({
+						...entry,
+						path: entry.path.slice(prefix.length)
+					}));
+					runtimeName = runtimeNameOf(current.source.bundle.name);
+					files = await composition.forkBundle({
+						files,
+						from: current.source.bundle,
+						to: identity,
+						runtimeName
+					});
+				} else {
+					for (const path of Object.keys(current.overlays)) if (path.startsWith("skills/")) {
+						const name = path.split("/")[1];
+						if (!current.mounts.some((mount) => mount.bundle.name === name && mount.instanceId)) throw new Error("Legacy Kit contains independent Bundle edits. Preserve them as Bundle copies before migrating this Kit.");
+					}
+					files = allFiles.filter((entry) => !entry.path.startsWith("skills/"));
+					for (const old of current.mounts) {
+						const prefix = `skills/${old.bundle.name}/`;
+						let bundleFiles = allFiles.filter((entry) => entry.path.startsWith(prefix)).map((entry) => ({
+							...entry,
+							path: entry.path.slice(prefix.length)
+						}));
+						let bundle = pin(old.bundle), authority;
+						if (old.instanceId) {
+							const linked = active(await tx.read(old.instanceId));
+							bundle = linked.recordVersion === 2 ? linked.bundle : localPin("bundle", old.bundle.version, old.instanceId);
+							authority = localSourceId("bundle", bundle);
+							bundleFiles = await composition.forkBundle({
+								files: bundleFiles,
+								from: old.bundle,
+								to: bundle,
+								runtimeName: old.bundle.name
+							});
+						} else {
+							const trusted = await catalog.captureBundle(bundle);
+							if (canonicalFiles(trusted.files) !== canonicalFiles(bundleFiles)) throw new Error("Legacy Bundle bytes differ from the trusted catalog. Migrate a separate local Bundle before adopting this source.");
+							authority = requireSourceId(trusted.sourceId);
+						}
+						mounts.push({
+							bindingKey: old.bundle.name,
+							bundle: {
+								...bundle,
+								source: await retain(tx, bundleFiles, authority),
+								...old.instanceId ? {
+									instanceId: old.instanceId,
+									revision: old.revision
+								} : {}
+							}
+						});
+					}
+				}
+				const next = {
+					...current,
+					recordVersion: 2,
+					[current.kind]: identity,
+					sourceId,
+					baseSnapshot: (await retain(tx, files, sourceId)).snapshot,
+					overlays: {},
+					mounts,
+					...current.kind === "bundle" ? { runtimeName } : {},
+					migration: {
+						fromRevision: current.revision,
+						fromSnapshot: current.baseSnapshot
+					}
+				};
+				delete next.bundlePath;
+				if (current.kind === "kit") next.baseSnapshot = (await retain(tx, await projectedKit(next, mounts), sourceId)).snapshot;
+				return tx.migrate(id, expectedRevision, next);
+			});
+			return describe(migrated);
+		}
+	};
+}
+//#endregion
+//#region src/node/studio-instance-composition.mjs
+/** Core-backed Studio adapters over trusted captures; no filesystem, installation or execution port. */
+const MAX_TREE_BYTES = 16777216;
+const MAX_TREE_FILES = 4096;
+const MAX_CLOSURE_BYTES = 67108864;
+const MAX_CLOSURE_FILES = 16384;
+const pinOf = (value) => {
+	if (!value || typeof value.name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(value.name) || typeof value.version !== "string" || !/^\d+\.\d+$/.test(value.version)) throw new Error("Studio composition requires exact content pins.");
+	return {
+		name: value.name,
+		version: value.version
+	};
+};
+const samePin$1 = (a, b) => a.name === b.name;
+const sourceIdOf = (value) => {
+	if (typeof value !== "string" || !value || value.length > 4096 || /[\u0000-\u001f\u007f]/u.test(value)) throw new Error("Trusted Bundle source identity is required.");
+	return value;
+};
+const decode = (bytes) => {
+	const value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	if (value.includes("\0")) throw new Error("Studio definition text contains binary content.");
+	return value;
+};
+const entry = (path, content) => ({
+	path,
+	base64: Buffer.from(content, "utf8").toString("base64")
+});
+/** The virtual filesystem never falls back to the host filesystem. */
+function memorySource(entries, budget = {
+	bytes: 0,
+	files: 0
+}) {
+	if (!Array.isArray(entries) || entries.length > MAX_TREE_FILES) throw new Error("Studio source exceeds 4096 files.");
+	const root = resolve("/studio-instance-memory", randomUUID()), files = /* @__PURE__ */ new Map(), directories = /* @__PURE__ */ new Set([""]);
+	let total = 0;
+	for (const item of entries) {
+		const { path, base64 } = item ?? {};
+		if (typeof path !== "string" || !path || path.length > 1024 || /[\\:\u0000-\u001f\u007f]/u.test(path) || path.split("/").some((part) => !part || [
+			".",
+			"..",
+			".git",
+			"node_modules"
+		].includes(part)) || path.split("/").length > 32 || files.has(path) || typeof base64 !== "string") throw new Error("Invalid or duplicate Studio source path.");
+		const bytes = Buffer.from(base64, "base64");
+		if (bytes.toString("base64") !== base64) throw new Error("Studio source base64 is not canonical.");
+		total += bytes.length;
+		if (total > MAX_TREE_BYTES) throw new Error("Studio source exceeds 16 MiB.");
+		files.set(path, bytes);
+		const parts = path.split("/");
+		for (let count = 1; count < parts.length; count++) directories.add(parts.slice(0, count).join("/"));
+	}
+	if ([...files.keys()].some((path) => directories.has(path))) throw new Error("Studio source file conflicts with a directory.");
+	budget.bytes += total;
+	budget.files += files.size;
+	if (budget.bytes > MAX_CLOSURE_BYTES || budget.files > MAX_CLOSURE_FILES) throw new Error("Studio composition exceeds its 64 MiB or 16384 file budget.");
+	const keyOf = (path) => {
+		const rel = relative(root, resolve(path));
+		if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error("Studio composition path escapes captured source.");
+		return rel.split(sep).join("/");
+	};
+	return {
+		root,
+		fs: {
+			async readText(path) {
+				const bytes = files.get(keyOf(path));
+				return bytes === void 0 ? void 0 : bytes.toString("utf8");
+			},
+			async readBytes(path) {
+				const bytes = files.get(keyOf(path));
+				return bytes === void 0 ? void 0 : Buffer.from(bytes);
+			},
+			async listDir(path) {
+				const key = keyOf(path), prefix = key ? `${key}/` : "";
+				return [...new Set([...files.keys()].filter((name) => name.startsWith(prefix)).map((name) => name.slice(prefix.length).split("/")[0]))].sort();
+			},
+			async isDirectory(path) {
+				return directories.has(keyOf(path));
+			},
+			async realPath(path) {
+				keyOf(path);
+				return resolve(path);
+			}
+		},
+		entries: [...files].map(([path, bytes]) => ({
+			path,
+			base64: bytes.toString("base64")
+		})),
+		text(path) {
+			const bytes = files.get(path);
+			if (bytes === void 0) throw new Error(`Missing Studio definition ${path}.`);
+			return decode(bytes);
+		}
+	};
+}
+/** Edit only one top-level YAML scalar; comments and every other source byte survive. */
+function scalarEdit(source, key, value, allowInsert = false) {
+	const document = parseDocument(source);
+	if (document.errors.length || !isMap(document.contents)) throw new Error("Studio requires one valid YAML mapping.");
+	const node = document.get(key, true), encoded = JSON.stringify(value);
+	if (node !== void 0) {
+		if (!isScalar(node) || !node.range) throw new Error(`Studio cannot rewrite non-scalar ${key}.`);
+		return source.slice(0, node.range[0]) + encoded + source.slice(node.range[1]);
+	}
+	if (!allowInsert) throw new Error(`Missing required identity field ${key}.`);
+	if (document.contents.flow) {
+		const index = document.contents.range[0] + 1;
+		return source.slice(0, index) + `${key}: ${encoded}${document.contents.items.length ? ", " : ""}` + source.slice(index);
+	}
+	const first = document.contents.items[0]?.key;
+	if (!first?.range) throw new Error("Studio cannot insert identity into an empty mapping.");
+	const start = source.lastIndexOf("\n", first.range[0] - 1) + 1;
+	const indent = source.slice(start, first.range[0]), newline = source.includes("\r\n") ? "\r\n" : "\n";
+	return source.slice(0, start) + `${indent}${key}: ${encoded}${newline}` + source.slice(start);
+}
+function projectRelationIdentifiers(source, from, to) {
+	if (from === to || !source.trim()) return source;
+	const document = parseDocument(source);
+	if (document.errors.length || !isMap(document.contents)) throw new Error("Studio cannot project malformed relations.yaml.");
+	const relations = document.get("relations", true), edits = [];
+	const rebase = (node, separator) => {
+		if (!isScalar(node) || typeof node.value !== "string" || !node.range || !node.value.startsWith(`${from}${separator}`)) return;
+		edits.push({
+			start: node.range[0],
+			end: node.range[1],
+			value: JSON.stringify(to + node.value.slice(from.length))
+		});
+	};
+	if (isSeq(relations)) for (const relation of relations.items) {
+		if (!isMap(relation)) continue;
+		for (const key of [
+			"type",
+			"meaning",
+			"inverse"
+		]) rebase(relation.get(key, true), ":");
+		for (const key of ["domain", "range"]) {
+			const values = relation.get(key, true);
+			if (isSeq(values)) for (const value of values.items) rebase(value, "/");
+		}
+	}
+	for (const edit of edits.sort((a, b) => b.start - a.start)) source = source.slice(0, edit.start) + edit.value + source.slice(edit.end);
+	return source;
+}
+async function projectMindset(source, kit, mounts, describeBundle, allowEmptyDraft = false) {
+	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+	if (!match) throw new Error("Kit Mindset requires explicit YAML frontmatter.");
+	const parsed = parseFrontmatter(source, "mindset.md");
+	const catalogs = [...parsed.body.matchAll(/<design_skills>\s*([\s\S]*?)\s*<\/design_skills>/g)];
+	const emptyDraft = allowEmptyDraft && catalogs.length === 1 && catalogs[0][1].trim() === "";
+	if (!emptyDraft) parseMindsetSkillNames(parsed.body, String(parsed.meta.name));
+	let frontmatter = scalarEdit(match[1], "name", kit.name);
+	frontmatter = scalarEdit(frontmatter, "version", kit.version);
+	const frontStart = source.indexOf(match[1]), frontEnd = frontStart + match[1].length;
+	const renamed = source.slice(0, frontStart) + frontmatter + source.slice(frontEnd);
+	const bodyStart = renamed.length - parseFrontmatter(renamed, "mindset.md").body.length;
+	const marker = renamed.indexOf("<design_skills>", bodyStart);
+	if (marker < 0) throw new Error("Mindset has no generated Bundle catalog block.");
+	const start = marker + 15;
+	const end = renamed.indexOf("</design_skills>", start);
+	const block = renamed.slice(start, end), headings = [...block.matchAll(/^##\s+(.+?)\s*$/gm)];
+	if (end < start || headings.length === 0 && !emptyDraft) throw new Error("Mindset generated Bundle catalog is empty or malformed.");
+	const sections = new Map(headings.map((heading, index) => [heading[1], block.slice(heading.index, headings[index + 1]?.index ?? block.length)]));
+	const newline = renamed.includes("\r\n") ? "\r\n" : "\n";
+	const selected = [];
+	for (const mount of mounts) if (sections.has(mount.bindingKey)) selected.push(sections.get(mount.bindingKey));
+	else {
+		const description = (await describeBundle(mount)).trim().replace(/\r\n?/g, "\n");
+		if (!description) throw new Error(`Bundle ${mount.name} needs a SKILL frontmatter routing description before it can enter the Mindset catalog.`);
+		const escaped = description.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\n", newline);
+		selected.push(`## ${mount.bindingKey}${newline}${newline}${escaped}${newline}${newline}`);
+	}
+	const generated = block.slice(0, headings[0]?.index ?? block.length) + selected.join("");
+	const projected = renamed.slice(0, start) + generated + renamed.slice(end);
+	const names = allowEmptyDraft && mounts.length === 0 ? [] : parseMindsetSkillNames(parseFrontmatter(projected, "mindset.md").body, kit.name);
+	if (JSON.stringify(names) !== JSON.stringify(mounts.map((mount) => mount.bindingKey))) throw new Error("Generated Mindset catalog differs from Kit mounts.");
+	return projected;
+}
+/**
+* trusted.listBundles(): Promise<Pin[]>; trusted.captureBundle(pin): {files,sourceId};
+* trusted.captureKit(pin): {files,title?}. Captures are exact, host-selected sources.
+* composition.projectMounts additionally accepts resolveBundle(pin) for retained local sources;
+* the trusted installed capture is used only when that resolver is omitted.
+* Optional trusted.preview overrides the default Core-backed retained-source preview.
+* Returned catalog/composition match createStudioInstances; there is no legacy-tree fallback.
+*/
+function createStudioInstanceAdapters(trusted) {
+	if (!trusted || ![
+		"listBundles",
+		"captureBundle",
+		"captureKit"
+	].every((key) => typeof trusted[key] === "function")) throw new Error("Trusted independent catalog capture ports are required.");
+	const loadBundle = async (files, sourceId, expected, budget) => {
+		const source = memorySource(files, budget);
+		for (const path of [
+			"skill.yaml",
+			"SKILL.md",
+			"schema.yaml",
+			"validation.yaml"
+		]) source.text(path);
+		return {
+			source,
+			content: await loadDesignBundle(source.fs, {
+				rootDir: source.root,
+				sourceId: sourceIdOf(sourceId),
+				current: true
+			}, { name: pinOf(expected).name })
+		};
+	};
+	const compileKit = async ({ kit, kitFiles, mounts, resolveBundle }) => {
+		const expected = pinOf(kit), budget = {
+			bytes: 0,
+			files: 0
+		}, source = memorySource(kitFiles, budget);
+		const declared = parseKitMounts(source.text("kit.yaml"));
+		const selected = mounts.map((mount) => ({
+			bindingKey: mount.bindingKey,
+			...pinOf(mount.bundle ?? mount)
+		}));
+		const membership = (mounts) => mounts.map(({ bindingKey, name }) => ({
+			bindingKey,
+			name
+		}));
+		if (JSON.stringify(membership(declared)) !== JSON.stringify(membership(selected))) throw new Error("Selected mounts differ from authoritative kit.yaml.");
+		const loaded = await loadDesignKit(source.fs, source.root, {
+			sourceId: `local:kit:${expected.name}`,
+			current: true,
+			resolveBundle: async (pin) => {
+				if (!declared.some((mount) => samePin$1(mount, pin))) throw new Error("Core requested an undeclared Bundle.");
+				const capture = await resolveBundle(pin);
+				if (!capture) throw new Error(`Missing exact Bundle ${pin.name}@${pin.version}.`);
+				return (await loadBundle(capture.files, capture.sourceId, pin, budget)).content;
+			}
+		});
+		if (!samePin$1({
+			name: loaded.name,
+			version: String(loaded.version)
+		}, expected)) throw new Error("Kit source identity differs from its exact pin.");
+		return loaded;
+	};
+	const previewRetained = async (input) => {
+		const failure = (code, message) => ({ diagnostics: [{
+			code,
+			message
+		}] });
+		if (!input || !["kit", "bundle"].includes(input.kind) || !Number.isSafeInteger(input.revision) || input.revision < 0) return failure("preview.request", "Select a retained Kit or Bundle and a non-negative revision.");
+		const { kind, revision, sampleSource, runtimeName, sourceId } = input;
+		let bundle, kit, kitFiles, bundleFiles, mounts;
+		const resolveBundle = input.resolveBundle;
+		try {
+			bundle = pinOf(input.bundle);
+			if (kind === "kit") {
+				kit = pinOf(input.kit);
+				kitFiles = structuredClone(input.kitFiles);
+				mounts = structuredClone(input.mounts);
+				if (!Array.isArray(mounts) || !mounts.some((mount) => samePin$1(mount.bundle ?? mount, bundle))) return failure("preview.bundle_pin", "Select an exact mounted Bundle.");
+				if (typeof resolveBundle !== "function") return failure("preview.request", "Kit preview requires its retained Bundle resolver.");
+			} else {
+				if (input.kit !== void 0) return failure("preview.request", "A standalone Bundle preview cannot claim a Kit context.");
+				bundleFiles = structuredClone(input.bundleFiles);
+			}
+			let compiled, retained;
+			const oversizedPanel = (files) => Array.isArray(files) && files.some((file) => file.path === "panel.yaml" && typeof file.base64 === "string" && Buffer.byteLength(file.base64, "base64") > 1048576);
+			if (kind === "bundle") {
+				if (oversizedPanel(bundleFiles)) return failure("preview.size", "Panel source is limited to 1 MiB.");
+				retained = await loadBundle(bundleFiles, sourceId, bundle);
+				compiled = retained.content.skill;
+				if (runtimeName !== void 0 && compiled.name !== runtimeName) return failure("preview.bundle_pin", "The retained runtime name does not match the selected Bundle.");
+			} else {
+				const requested = parseKitMounts(memorySource(kitFiles).text("kit.yaml")).find((mount) => mount.name === bundle.name);
+				if (!requested) return failure("preview.bundle_pin", "The Bundle is outside the Kit declaration.");
+				const captured = await resolveBundle(requested);
+				if (!captured) return failure("preview.bundle_pin", "The retained Bundle source is missing.");
+				const selected = {
+					files: structuredClone(captured.files),
+					sourceId: captured.sourceId
+				};
+				if (oversizedPanel(selected.files)) return failure("preview.size", "Panel source is limited to 1 MiB.");
+				compiled = (await compileKit({
+					kit,
+					kitFiles,
+					mounts,
+					resolveBundle: (pin) => samePin$1(pin, bundle) ? Promise.resolve(selected) : resolveBundle(pin)
+				})).skills.find((skill) => (skill.catalogName ?? skill.name) === bundle.name);
+				retained = { source: memorySource(selected.files) };
+			}
+			if (!compiled) return failure("preview.bundle_pin", "The source does not match the selected Bundle version.");
+			if (typeof compiled.metadata?.panelYaml !== "string") return failure("preview.not_declarative", "Only an existing declarative Panel can be previewed.");
+			let sample = sampleSource;
+			if (sample === void 0) {
+				const example = retained.source.entries.find((file) => file.path === "reference/preview.json");
+				if (example) sample = retained.source.text(example.path);
+				else if (compiled.metadata.panelManifest?.initial_values !== void 0) sample = JSON.stringify(compiled.metadata.panelManifest.initial_values);
+				else return failure("preview.sample_missing", "Add reference/preview.json, Panel initial_values, or explicit isolated sample JSON.");
+			}
+			return finalizeStudioPanelPreview({
+				compiled,
+				bundle: {
+					...bundle,
+					version: String(compiled.version)
+				},
+				...kit === void 0 ? {} : { kit },
+				revision,
+				sampleSource: sample,
+				readSampleResource: (path) => retained.source.entries.some((file) => file.path === path) ? retained.source.text(path) : void 0
+			});
+		} catch (error) {
+			return failure("preview.definition", error instanceof Error ? error.message : String(error));
+		}
+	};
+	const catalog = {
+		async listBundles() {
+			const pins = await trusted.listBundles();
+			if (!Array.isArray(pins) || pins.length > 1024) throw new Error("Studio catalog exceeds 1024 Bundle pins.");
+			const seen = /* @__PURE__ */ new Set(), result = [];
+			for (const value of pins) {
+				const pin = pinOf(value), key = `${pin.name}@${pin.version}`;
+				if (seen.has(key)) throw new Error(`Ambiguous exact Bundle ${key}.`);
+				seen.add(key);
+				const captured = await catalog.captureBundle(pin);
+				result.push({
+					...pin,
+					title: captured.title,
+					runtimeName: captured.runtimeName,
+					...captured.description === void 0 ? {} : { description: captured.description },
+					...captured.displayDescription === void 0 ? {} : { displayDescription: { ...captured.displayDescription } }
+				});
+			}
+			return result;
+		},
+		async captureBundle(value) {
+			const pin = pinOf(value), raw = await trusted.captureBundle(pin);
+			const { source, content } = await loadBundle(raw.files, raw.sourceId, pin);
+			return {
+				files: source.entries,
+				sourceId: raw.sourceId,
+				title: { ...content.skill.title },
+				runtimeName: content.skill.name,
+				...typeof content.skill.description === "string" ? { description: content.skill.description } : {},
+				...content.skill.pickerDescription ? { displayDescription: { ...content.skill.pickerDescription } } : {}
+			};
+		},
+		async captureKit(value) {
+			const kit = pinOf(value), raw = await trusted.captureKit(kit), source = memorySource(raw.files);
+			if (source.entries.some((file) => file.path.startsWith("skills/"))) throw new Error("Kit capture must not contain embedded Bundle trees.");
+			const mounts = parseKitMounts(source.text("kit.yaml"));
+			await compileKit({
+				kit,
+				kitFiles: source.entries,
+				mounts,
+				resolveBundle: (pin) => trusted.captureBundle(pin)
+			});
+			return {
+				files: source.entries,
+				mounts,
+				...raw.title === void 0 ? {} : { title: raw.title }
+			};
+		}
+	};
+	const composition = {
+		loadKit: compileKit,
+		async forkBundle({ files, from, to, runtimeName }) {
+			from = pinOf(from);
+			to = pinOf(to);
+			if (to.name === from.name || to.version !== from.version) throw new Error("A fork requires a new catalog identity and preserves its source version.");
+			const before = await loadBundle(files, `studio:fork-source:${from.name}`, from);
+			if (before.content.skill.name !== runtimeName) throw new Error("Fork runtime name does not match its retained source.");
+			const presentation = before.content.skill.metadata?.skillManifest?.presentation;
+			if (presentation?.mode === "native" || presentation?.mode === "auto" && presentation.renderer && !before.content.skill.metadata?.panelYaml) throw new Error("Native-only Bundles cannot be forked: the new identity has no trusted native renderer authority.");
+			const manifest = scalarEdit(before.source.text("skill.yaml"), "identity", to.name, true);
+			const next = before.source.entries.map((file) => file.path === "skill.yaml" ? entry(file.path, manifest) : file);
+			const after = await loadBundle(next, `local:bundle:${to.name}`, to);
+			if (after.content.skill.name !== runtimeName || after.content.skill.content !== before.content.skill.content) throw new Error("A fork cannot alter the runtime name or Bundle method.");
+			return next;
+		},
+		async projectMounts({ kit, kitFiles, mounts, allowEmptyDraft = false, resolveBundle = (pin) => trusted.captureBundle(pin) }) {
+			kit = pinOf(kit);
+			const declaration = stringify({
+				version: 1,
+				mounts: mounts.map((mount) => ({
+					bindingKey: mount.bindingKey,
+					...pinOf(mount)
+				}))
+			});
+			const normalized = allowEmptyDraft && mounts.length === 0 ? [] : parseKitMounts(declaration), source = memorySource(kitFiles);
+			const budget = {
+				bytes: 0,
+				files: 0
+			};
+			const originalMindset = source.text("mindset.md");
+			let mindset;
+			try {
+				mindset = await projectMindset(originalMindset, kit, normalized, async (mount) => {
+					const captured = await resolveBundle(pinOf(mount));
+					if (!captured) throw new Error(`Missing exact Bundle ${mount.name}@${mount.version} for catalog projection.`);
+					const loaded = await loadBundle(captured.files, captured.sourceId, mount, budget);
+					if (loaded.content.skill.name !== mount.bindingKey) throw new Error("Bundle bindingKey must preserve the runtime name.");
+					return loaded.content.skill.description;
+				}, allowEmptyDraft);
+			} catch (error) {
+				if (!allowEmptyDraft) throw error;
+				return [...composition.projectSourceIdentity({
+					kind: "kit",
+					files: source.entries,
+					identity: kit
+				}).filter((file) => file.path !== "kit.yaml"), entry("kit.yaml", declaration)];
+			}
+			const originalName = String(parseFrontmatter(originalMindset, "mindset.md").meta.name);
+			return [
+				...source.entries.filter((file) => !["kit.yaml", "mindset.md"].includes(file.path)).map((file) => {
+					if (file.path !== "relations.yaml" || originalName === kit.name) return file;
+					source.text(file.path);
+					const text = Buffer.from(file.base64, "base64").toString("utf8");
+					const projected = projectRelationIdentifiers(text, originalName, kit.name);
+					return projected === text ? file : entry(file.path, projected);
+				}),
+				entry("mindset.md", mindset),
+				entry("kit.yaml", declaration)
+			];
+		},
+		projectSourceIdentity({ kind, files, identity }) {
+			const source = memorySource(files);
+			if (kind === "bundle") return source.entries.map((file) => {
+				if (file.path !== "skill.yaml") return file;
+				try {
+					return entry(file.path, scalarEdit(source.text(file.path), "identity", identity.name, true));
+				} catch {
+					return file;
+				}
+			});
+			let originalName;
+			return source.entries.map((file) => {
+				if (file.path !== "mindset.md") return file;
+				try {
+					const text = source.text(file.path), match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+					if (!match) return file;
+					originalName = parseFrontmatter(text, "mindset.md").meta.name;
+					let frontmatter = scalarEdit(match[1], "name", identity.name, true);
+					frontmatter = scalarEdit(frontmatter, "version", identity.version, true);
+					const start = text.indexOf(match[1]);
+					return entry(file.path, text.slice(0, start) + frontmatter + text.slice(start + match[1].length));
+				} catch {
+					return file;
+				}
+			}).map((file) => {
+				if (file.path !== "relations.yaml" || typeof originalName !== "string" || originalName === identity.name) return file;
+				try {
+					return entry(file.path, projectRelationIdentifiers(source.text(file.path), originalName, identity.name));
+				} catch {
+					return file;
+				}
+			});
+		},
+		async validateBundle({ bundle, bundleFiles, sourceId, runtimeName }) {
+			const { content } = await loadBundle(bundleFiles, sourceId, bundle);
+			if (content.skill.name !== runtimeName) throw new Error("Bundle runtime name differs from the retained method.");
+		},
+		async validateKit(input) {
+			await compileKit(input);
+		},
+		preview: typeof trusted.preview === "function" ? (input) => trusted.preview(input) : previewRetained
+	};
+	return {
+		catalog,
+		composition
+	};
+}
+//#endregion
+//#region src/node/studio-authoring.mjs
+/**
+* Read/prepare capability for one trusted Studio instance revision.
+*
+* The host authenticates and binds the native invocation before constructing this
+* adapter. Scope is never a model argument. Pass only the existing instance
+* read/readFile/prepareChanges ports and a same-build component catalog reader
+* returning the JSON projection used by design_list_panel_components.
+*
+* read({paths?}) returns coherent, bounded source text plus the actual catalog.
+* allowedPaths seeds the initial read; the current instance and revision bind
+* subsequent legal reads, replacements and new files.
+* prepare({changes}) returns {request,candidate}: request.changes contains full
+* replacement files for the existing UI's saveChanges path, while candidate is
+* S1's exact diff/preview/digest. Neither operation saves, publishes, dispatches
+* a model, or proves native execution. This first capability excludes deletion.
+*/
+const object = (value, keys, label) => {
+	if (!value || typeof value !== "object" || Array.isArray(value) || Reflect.ownKeys(value).some((key) => !keys.includes(key))) throw new Error(`Invalid ${label}; scope and authority cannot be supplied by the caller.`);
+	return value;
+};
+const samePin = (a, b) => a?.name === b?.name && a?.version === b?.version;
+const changed = () => /* @__PURE__ */ new Error("Authoring instance changed. Reopen and explicitly bind the current revision; do not retry this scope automatically.");
+function createStudioAuthoring({ scope, instances, readComponents } = {}) {
+	object(scope, [
+		"id",
+		"expectedRevision",
+		"allowedPaths",
+		"bundle"
+	], "trusted authoring scope");
+	if (!instances || ![
+		"read",
+		"readFile",
+		"prepareChanges"
+	].every((key) => typeof instances[key] === "function") || typeof readComponents !== "function" || !Array.isArray(scope.allowedPaths)) throw new Error("Authoring requires existing instance read/prepare ports, an initial reading focus and the actual component catalog reader.");
+	const normalized = normalizeStudioInstanceChanges({
+		id: scope.id,
+		expectedRevision: scope.expectedRevision,
+		changes: scope.allowedPaths.map((path) => ({
+			path,
+			content: ""
+		})),
+		...scope.bundle === void 0 ? {} : { bundle: scope.bundle }
+	});
+	const binding = Object.freeze({
+		id: normalized.id,
+		expectedRevision: normalized.expectedRevision,
+		allowedPaths: Object.freeze(normalized.changes.map((change) => change.path)),
+		...normalized.bundle ? { bundle: normalized.bundle } : {}
+	});
+	const readInstance = instances.read.bind(instances), readFile = instances.readFile.bind(instances);
+	const prepareChanges = instances.prepareChanges.bind(instances);
+	const requestFor = (changes) => normalizeStudioInstanceChanges({
+		id: binding.id,
+		expectedRevision: binding.expectedRevision,
+		changes,
+		...binding.bundle ? { bundle: binding.bundle } : {}
+	});
+	const checkPaths = (paths) => {
+		return requestFor(paths.map((path) => ({
+			path,
+			content: ""
+		}))).changes.map((change) => change.path);
+	};
+	const current = async () => {
+		const record = await readInstance({ id: binding.id });
+		if (!record || record.id !== binding.id || record.revision !== binding.expectedRevision || record.deletedAt) throw changed();
+		if (!["kit", "bundle"].includes(record.kind) || !Array.isArray(record.files)) throw new Error("Authoring requires a current complete-source working copy.");
+		if (binding.bundle && (record.kind === "bundle" ? !samePin(binding.bundle, record.bundle) : !record.mounts?.some((mount) => samePin(binding.bundle, mount.bundle)))) throw new Error("Authoring preview Bundle is outside this exact instance.");
+		return record;
+	};
+	const components = async () => {
+		const value = await readComponents();
+		if (!value || !Array.isArray(value.components) || !value.components.length) throw new Error("The actual authoring component catalog is unavailable.");
+		const text = JSON.stringify(value);
+		if (Buffer.byteLength(text) > STUDIO_INSTANCE_CHANGE_LIMITS.sampleBytes) throw new Error("Authoring component catalog exceeds the 256 KiB response budget.");
+		return JSON.parse(text);
+	};
+	return Object.freeze({
+		async read(input = {}) {
+			object(input, ["paths"], "authoring read request");
+			if (input.paths !== void 0 && !Array.isArray(input.paths)) throw new Error("Select an exact list of scoped source paths.");
+			const paths = checkPaths(input.paths ?? binding.allowedPaths);
+			const record = await current();
+			const selected = paths.map((path) => ({
+				path,
+				file: record.files.find((file) => file.path === path)
+			}));
+			if (selected.some(({ file }) => file && (!file.editable || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > STUDIO_INSTANCE_CHANGE_LIMITS.fileBytes))) throw new Error("Scoped source must be editable UTF-8 text of at most 1 MiB per file.");
+			if (selected.reduce((bytes, { file }) => bytes + (file?.bytes ?? 0), 0) > STUDIO_INSTANCE_CHANGE_LIMITS.totalBytes) throw new Error("Authoring read exceeds the 4 MiB text budget; select fewer paths.");
+			const catalog = await components();
+			const files = await Promise.all(selected.map(async ({ path, file }) => {
+				if (!file) return {
+					path,
+					exists: false
+				};
+				const value = await readFile({
+					id: binding.id,
+					path
+				});
+				if (value?.id !== binding.id || value.revision !== binding.expectedRevision || value.path !== path) throw changed();
+				return {
+					path,
+					exists: true,
+					content: value.content
+				};
+			}));
+			const existing = files.filter((file) => file.exists);
+			if (existing.length) requestFor(existing.map(({ path, content }) => ({
+				path,
+				content
+			})));
+			await current();
+			return {
+				scope: binding,
+				files,
+				components: catalog
+			};
+		},
+		async prepare(input) {
+			object(input, ["changes"], "authoring prepare request");
+			if (!Array.isArray(input.changes)) throw new Error("Provide scoped complete-file replacements.");
+			for (const change of input.changes) {
+				object(change, ["path", "content"], "authoring file replacement");
+				if (change.content === null) throw new Error("File deletion is not granted by this authoring capability.");
+			}
+			const request = requestFor(input.changes);
+			await current();
+			const catalog = await components();
+			const candidate = await prepareChanges(request);
+			await current();
+			if (candidate?.id !== binding.id || candidate.baseRevision !== binding.expectedRevision || candidate.revision !== binding.expectedRevision + 1 || typeof candidate.valid !== "boolean" || !/^[a-f0-9]{64}$/.test(candidate.digest) || !Array.isArray(candidate.diagnostics) || !Array.isArray(candidate.diff) || candidate.diff.some((file) => !request.changes.some((change) => change.path === file.path)) || candidate.preview && candidate.preview.revision !== candidate.revision) throw new Error("Prepared candidate does not match this authoring revision and file set.");
+			return {
+				scope: binding,
+				components: catalog,
+				request,
+				candidate: structuredClone(candidate)
+			};
+		}
+	});
+}
+//#endregion
+export { createStudioAuthoring, createStudioDraftPorts, createStudioInstanceAdapters, createStudioInstances };