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

package/lib/authoring-agent.types-QLa61eE6.d.ts

@@ -0,0 +1,88 @@
+import { Agent } from "@deepseek-ai/dsh-agent";
+//#region src/authoring-agent.types.d.ts
+interface StudioAuthoringScope {
+  readonly id: string;
+  readonly expectedRevision: number;
+  /** Initial read focus; subsequent reads and file changes stay in this bound object/revision. */
+  readonly allowedPaths: readonly string[];
+  readonly bundle?: Readonly<{
+    name: string;
+    version: string;
+  }>;
+}
+/** The existing S3 capability. Its receipt remains the sole candidate source. */
+interface StudioAuthoringPorts {
+  read(input?: {
+    paths?: string[];
+  }): Promise<unknown>;
+  prepare(input: {
+    changes: {
+      path: string;
+      content: string;
+    }[];
+  }): Promise<unknown>;
+}
+interface StudioAuthoringReference {
+  readonly sessionId: string;
+  readonly parentSessionId: string;
+  readonly invocationId: string;
+  readonly epoch: string;
+  readonly messageId: string;
+  readonly afterSeq: number;
+  readonly scope: StudioAuthoringScope;
+}
+interface StudioAuthoringObservation {
+  readonly reference: StudioAuthoringReference;
+  readonly status: 'queued' | 'running' | 'completed' | 'cancelled' | 'failed' | 'unknown';
+  readonly consumed: boolean;
+  readonly turn: number | null;
+  readonly terminal: boolean;
+  readonly reason?: string;
+  readonly throughSeq: number;
+  readonly source: 'live' | 'prepared';
+  /** This adapter witnessed a successful scoped native flush; prepared-cache reads alone do not prove it. */
+  readonly durable: boolean;
+  readonly pendingInput: boolean;
+  readonly diagnostic?: string;
+  /** Public messages and tool activity from this invocation's native event range. */
+  readonly conversation?: {
+    readonly rows: readonly {
+      id: string;
+      role: 'assistant' | 'tool';
+      label: string;
+      text: string;
+      status: string;
+    }[];
+    readonly omitted: number;
+  };
+}
+interface StudioAuthoringRequest {
+  readonly parent: Agent;
+  readonly invocationId: string;
+  readonly scope: StudioAuthoringScope;
+  readonly workspaceRoot: string;
+  readonly prompt: string;
+  readonly ports: StudioAuthoringPorts;
+  readonly signal?: AbortSignal;
+  /** Retain this native address before the adapter attempts dispatch. */
+  readonly onReference?: (reference: StudioAuthoringReference) => void | Promise<void>;
+  /** A projection of the successful S3 tool receipt, not execution completion. */
+  readonly onPrepared?: (receipt: unknown) => void | Promise<void>;
+}
+interface StudioAuthoringResumeRequest extends StudioAuthoringRequest {
+  readonly previous: StudioAuthoringReference;
+  readonly explicit: true;
+}
+interface StudioAuthoringRun {
+  readonly reference: StudioAuthoringReference;
+  readonly result: Promise<StudioAuthoringObservation>;
+  observe(): Promise<StudioAuthoringObservation>;
+  /** null fences an invocation whose native turn has not started. */
+  cancel(options: {
+    expectedTurn: number | null;
+  }): Promise<StudioAuthoringObservation>;
+  readPrepared(): unknown | undefined;
+  dispose(): Promise<void>;
+}
+//#endregion
+export { StudioAuthoringResumeRequest as a, StudioAuthoringRequest as i, StudioAuthoringPorts as n, StudioAuthoringRun as o, StudioAuthoringReference as r, StudioAuthoringScope as s, StudioAuthoringObservation as t };

package/lib/authoring-entry.d.ts

@@ -0,0 +1,20 @@
+import { DshStudioAuthoringServiceConfig } from "./authoring-service.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/authoring-entry.d.ts
+type DshStudioAuthoringEntryConfig = Partial<DshStudioAuthoringServiceConfig>;
+declare const name = "studio-authoring";
+declare const inject: string[];
+/**
+ * Prepare private single-leaf roots, then mount the one existing Service.
+ * Failed or interrupted initialization preserves already-created directories
+ * and namespace metadata; no rollback or automatic retry is attempted.
+ * Async keeps this plugin callback non-constructible for Cordis activation.
+ */
+declare function apply(ctx: Context, config?: DshStudioAuthoringEntryConfig): Promise<void>;
+declare const _default: {
+  name: string;
+  inject: string[];
+  apply: typeof apply;
+};
+//#endregion
+export { DshStudioAuthoringEntryConfig, apply, _default as default, inject, name };

package/lib/authoring-entry.js

@@ -0,0 +1,77 @@
+import { prepareStudioAuthoringDirectory } from "./authoring-reference-store.js";
+import { t as DshStudioAuthoringService } from "./authoring-service-qGEk-IE_.js";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+//#region src/authoring-entry.ts
+const name = "studio-authoring";
+const inject = [...DshStudioAuthoringService.inject];
+/**
+* Prepare private single-leaf roots, then mount the one existing Service.
+* Failed or interrupted initialization preserves already-created directories
+* and namespace metadata; no rollback or automatic retry is attempted.
+* Async keeps this plugin callback non-constructible for Cordis activation.
+*/
+async function apply(ctx, config = {}) {
+	let closed = false;
+	let child;
+	let initialization;
+	let shutdown;
+	const close = () => {
+		if (shutdown) return shutdown;
+		closed = true;
+		const completion = Promise.withResolvers();
+		shutdown = completion.promise;
+		shutdown.catch(() => {});
+		let stop;
+		try {
+			stop = child?.dispose();
+		} catch (error) {
+			stop = Promise.reject(error);
+		}
+		Promise.allSettled([stop, initialization?.then(() => void 0, () => void 0)]).then((results) => {
+			const failures = results.filter((r) => r.status === "rejected").map((r) => r.reason);
+			if (failures.length) throw new AggregateError(failures, "Studio authoring entry cleanup failed");
+		}).then(completion.resolve, completion.reject);
+		return shutdown;
+	};
+	ctx.effect(() => close, "studio-authoring-entry");
+	ctx.on("internal/plugin", (fiber) => {
+		if (fiber === ctx.fiber && fiber.uid === null) close();
+	});
+	ctx.on("internal/status", (fiber) => {
+		if (fiber === ctx.fiber && (fiber.state === 5 || fiber.state === 4)) close();
+	});
+	try {
+		if (config === null || typeof config !== "object" || Array.isArray(config)) throw new TypeError("Studio authoring entry requires a trusted configuration object");
+		const roots = Object.freeze({
+			stateRoot: config.stateRoot === void 0 ? dshHomePath("yugoo-design-studio") : config.stateRoot,
+			workspaceRoot: config.workspaceRoot === void 0 ? dshHomePath("yugoo-design-studio-workspace") : config.workspaceRoot
+		});
+		const active = () => {
+			if (closed || ctx.fiber.uid === null) throw new Error("Studio authoring entry closed during initialization");
+		};
+		initialization = Promise.resolve().then(async () => {
+			active();
+			const stateRoot = await prepareStudioAuthoringDirectory(roots.stateRoot);
+			active();
+			const workspaceRoot = await prepareStudioAuthoringDirectory(roots.workspaceRoot);
+			active();
+			child = ctx.plugin(DshStudioAuthoringService, {
+				stateRoot,
+				workspaceRoot
+			});
+			await child;
+			active();
+		});
+	} catch (error) {
+		initialization = Promise.reject(error);
+	}
+	initialization.catch(() => {});
+	return initialization;
+}
+var authoring_entry_default = {
+	name,
+	inject,
+	apply
+};
+//#endregion
+export { apply, authoring_entry_default as default, inject, name };

package/lib/authoring-host-BlsA6wXz.js

@@ -0,0 +1,347 @@
+import { createStudioAuthoringSession } from "./authoring-session.js";
+import { createStudioAuthoringReferenceStore } from "./authoring-reference-store.js";
+import { createDshStudioInstanceAdapters, registerDshStudioCurrentKitSource } from "./authoring-sources.js";
+import { readStudioContentArchive } from "@yugoo-design/dsh-design-studio";
+import { isAbsolute } from "node:path";
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { createStudioInstances } from "@yugoo-design/dsh-design-studio/node";
+//#region src/authoring-content.ts
+/** Export and stateless archive decoding over the current S2 source authority. */
+async function createDshStudioContent({ instances }) {
+	return {
+		readArchive: async ({ source }) => readStudioContentArchive(source),
+		async exportContentArchive(input) {
+			if ("id" in input) return instances.exportArchive(input);
+			const current = await instances.editCurrent({
+				kind: input.kind,
+				[input.kind]: input.pin
+			});
+			return instances.exportArchive({
+				id: current.id,
+				expectedRevision: current.revision,
+				provenance: input.provenance
+			});
+		}
+	};
+}
+//#endregion
+//#region src/authoring-host.ts
+/** Host-only composition. S2 owns source/save, S5a addresses, S4 native execution. */
+const INSTANCE_METHODS = [
+	"read",
+	"list",
+	"listBundles",
+	"copy",
+	"editCurrent",
+	"captureKit",
+	"loadKit",
+	"create",
+	"importSources",
+	"rename",
+	"remove",
+	"readFile",
+	"saveFile",
+	"prepareChanges",
+	"saveChanges",
+	"updateMounts",
+	"preview",
+	"migrate",
+	"exportArchive"
+];
+const addressOf = (value) => ({
+	sessionId: value.sessionId,
+	epoch: value.epoch
+});
+const MAX_PREPARED_PROJECTIONS = 16;
+const MAX_PREPARED_BYTES = 33554432;
+const snapshot = (request) => ({
+	...request,
+	paths: structuredClone(request.paths),
+	...request.bundle === void 0 ? {} : { bundle: structuredClone(request.bundle) }
+});
+async function createDshStudioAuthoringHost(options) {
+	const { ctx, design, fs, stateRoot, workspaceRoot, readComponents } = options;
+	assert.ok(typeof workspaceRoot === "string" && isAbsolute(workspaceRoot), "An explicit Host-owned workspaceRoot is required");
+	assert.equal(typeof readComponents, "function", "The actual component catalog is required");
+	const references = await createStudioAuthoringReferenceStore({ stateRoot });
+	const shared = await createStudioInstances({
+		stateRoot,
+		...createDshStudioInstanceAdapters({
+			design,
+			fs
+		})
+	});
+	const content = await createDshStudioContent({ instances: shared });
+	const stopCurrentSource = registerDshStudioCurrentKitSource(design, shared);
+	const parents = /* @__PURE__ */ new Map();
+	const closing = /* @__PURE__ */ new Set(), cleanupFailures = /* @__PURE__ */ new Set();
+	let closed = false, disposing;
+	const active = () => assert.ok(!closed, "Studio authoring Host is disposed");
+	const exact = (parent) => assert.ok(parent && ctx.agents.get(parent.id) === parent, "The exact native authoring parent is disconnected");
+	const remember = (promise) => {
+		closing.add(promise);
+		promise.then(() => closing.delete(promise), (error) => {
+			closing.delete(promise);
+			cleanupFailures.add(error);
+		});
+		return promise;
+	};
+	const forParent = (parent) => {
+		active();
+		exact(parent);
+		const existing = parents.get(parent);
+		if (existing) return existing;
+		let parentClosed = false, parentDisposing;
+		const admitted = /* @__PURE__ */ new Set();
+		const guard = () => {
+			active();
+			assert.ok(!parentClosed, "Studio authoring parent facade is disposed");
+			exact(parent);
+		};
+		const admit = async (operation) => {
+			guard();
+			let settle;
+			const pending = new Promise((resolve) => {
+				settle = resolve;
+			});
+			admitted.add(pending);
+			try {
+				const value = await operation();
+				guard();
+				return value;
+			} finally {
+				admitted.delete(pending);
+				settle();
+			}
+		};
+		const instances = Object.freeze(Object.fromEntries(INSTANCE_METHODS.map((name) => [name, (...args) => {
+			const captured = structuredClone(args);
+			return admit(() => Reflect.apply(shared[name], shared, captured));
+		}])));
+		const prepared = /* @__PURE__ */ new Map();
+		let preparedBytes = 0;
+		const pin = (value) => value === void 0 ? void 0 : {
+			name: value.name,
+			version: value.version
+		};
+		const targetFor = (record, request) => {
+			assert.equal(record.id, request.id);
+			assert.equal(record.revision, request.expectedRevision, "Working copy changed; reopen before reviewing");
+			const bundle = record.kind === "bundle" ? record.bundle : request.bundle;
+			if (record.kind === "bundle" && request.bundle) assert.deepEqual(pin(request.bundle), pin(record.bundle), "Candidate Bundle pin changed");
+			if (record.kind === "kit" && bundle) assert.ok(record.mounts.some((mount) => JSON.stringify(pin(mount.bundle)) === JSON.stringify(pin(bundle))), "Candidate Bundle is not mounted in this Kit");
+			return {
+				id: record.id,
+				expectedRevision: record.revision,
+				...bundle ? { bundle: pin(bundle) } : {}
+			};
+		};
+		const prepareChanges = (request) => {
+			const captured = structuredClone(request);
+			return admit(async () => {
+				const candidate = await instances.prepareChanges(captured);
+				const target = targetFor(await instances.read({ id: captured.id }), captured);
+				guard();
+				const key = JSON.stringify({
+					request: captured,
+					digest: candidate.digest,
+					target
+				});
+				const previous = [...prepared.values()].find((row) => row.key === key);
+				if (previous) return structuredClone(previous.value);
+				const value = {
+					locator: {
+						requestId: randomUUID(),
+						...target,
+						digest: candidate.digest
+					},
+					prepared: {
+						request: captured,
+						candidate
+					}
+				};
+				const bytes = Buffer.byteLength(JSON.stringify(value)) + Buffer.byteLength(key);
+				assert.ok(bytes <= MAX_PREPARED_BYTES, "Prepared candidate exceeds the temporary review budget");
+				while (prepared.size >= MAX_PREPARED_PROJECTIONS || preparedBytes + bytes > MAX_PREPARED_BYTES) {
+					const oldest = prepared.keys().next().value;
+					preparedBytes -= prepared.get(oldest).bytes;
+					prepared.delete(oldest);
+				}
+				prepared.set(value.locator.requestId, {
+					value: structuredClone(value),
+					bytes,
+					key
+				});
+				preparedBytes += bytes;
+				return structuredClone(value);
+			});
+		};
+		const readConversationPrepared = (locator) => admit(async () => {
+			const row = prepared.get(locator.requestId);
+			assert.ok(row, "No prepared candidate for this exact live parent and request");
+			assert.deepEqual(locator, row.value.locator, "Prepared candidate locator or Bundle pin changed");
+			const { request, candidate } = row.value.prepared;
+			const { requestId: _requestId, digest: _digest, ...target } = locator;
+			assert.deepEqual(targetFor(await instances.read({ id: request.id }), request), target, "Prepared candidate source pin changed");
+			const current = await instances.prepareChanges(request);
+			assert.equal(current.digest, candidate.digest, "Prepared candidate digest changed");
+			return structuredClone(row.value.prepared);
+		});
+		let session;
+		const release = ctx.effect(() => {
+			session = createStudioAuthoringSession({
+				ctx,
+				parent,
+				instances,
+				workspaceRoot,
+				readComponents: () => admit(() => readComponents()),
+				retainReference: (reference) => admit(async () => {
+					assert.equal(reference.parentSessionId, String(parent.id));
+					await references.retain(reference);
+				})
+			});
+			return () => {
+				parentClosed = true;
+				prepared.clear();
+				preparedBytes = 0;
+				return session.dispose();
+			};
+		}, "studio-authoring-parent");
+		const readReference = (address) => {
+			const key = addressOf(address);
+			return admit(() => references.read({
+				...key,
+				parentSessionId: String(parent.id)
+			}));
+		};
+		const retained = async (address) => {
+			const reference = await readReference(address);
+			guard();
+			assert.ok(reference, "No retained Studio native address for this exact parent");
+			return reference;
+		};
+		let facade;
+		const wrap = (run) => {
+			const address = addressOf(run.reference);
+			return Object.freeze({
+				reference: structuredClone(run.reference),
+				result: run.result,
+				observe: () => facade.observe(address),
+				cancel: (input) => facade.cancel(address, input),
+				readPrepared: () => {
+					guard();
+					return run.readPrepared();
+				}
+			});
+		};
+		const disposeParent = () => {
+			if (parentDisposing) return parentDisposing;
+			parentClosed = true;
+			prepared.clear();
+			preparedBytes = 0;
+			const stop = Promise.resolve().then(() => session.dispose());
+			const unregister = Promise.resolve().then(() => release());
+			parentDisposing = remember(Promise.allSettled([
+				stop,
+				unregister,
+				...admitted
+			]).then((results) => {
+				const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+				if (failures.length) throw new AggregateError([...new Set(failures)], "Studio parent cleanup failed");
+			}));
+			return parentDisposing;
+		};
+		const guardedContent = Object.freeze({
+			readArchive: (input) => {
+				const captured = structuredClone(input);
+				return admit(() => content.readArchive(captured));
+			},
+			exportContentArchive: (input) => {
+				const captured = structuredClone(input);
+				return admit(() => content.exportContentArchive(captured));
+			}
+		});
+		facade = Object.freeze({
+			instances,
+			content: guardedContent,
+			prepareChanges,
+			readReference,
+			listReferences: () => admit(() => references.list({ parentSessionId: String(parent.id) })),
+			start: (request) => {
+				const captured = snapshot(request);
+				return admit(async () => wrap(await session.start(captured)));
+			},
+			resume: (request) => {
+				const captured = snapshot(request), previous = addressOf(request.previous), explicit = request.explicit;
+				return admit(async () => {
+					const reference = await retained(previous);
+					guard();
+					return wrap(await session.resume({
+						...captured,
+						previous: reference,
+						explicit
+					}));
+				});
+			},
+			observe: (address) => {
+				const key = addressOf(address);
+				return admit(async () => {
+					const reference = await retained(key);
+					guard();
+					return session.observe(reference);
+				});
+			},
+			cancel: (address, input) => {
+				const key = addressOf(address), expectedTurn = input.expectedTurn;
+				return admit(async () => {
+					const reference = await retained(key);
+					guard();
+					return session.cancel(reference, { expectedTurn });
+				});
+			},
+			readPrepared: (address) => {
+				if ("requestId" in address) return readConversationPrepared(structuredClone(address));
+				const key = addressOf(address);
+				return admit(async () => {
+					const reference = await retained(key);
+					guard();
+					return session.readPrepared(reference);
+				});
+			},
+			dispose: disposeParent
+		});
+		parents.set(parent, facade);
+		return facade;
+	};
+	const stopListening = ctx.on("agent/disposed", ({ agent }) => {
+		const facade = parents.get(agent);
+		if (!facade) return;
+		parents.delete(agent);
+		return facade.dispose();
+	});
+	const dispose = () => {
+		if (disposing) return disposing;
+		closed = true;
+		const stops = [...parents.values()].map((facade) => facade.dispose());
+		parents.clear();
+		disposing = Promise.allSettled([
+			Promise.resolve().then(() => stopListening()),
+			Promise.resolve().then(() => stopCurrentSource()),
+			...stops,
+			...closing
+		]).then((results) => {
+			const failures = /* @__PURE__ */ new Set([...cleanupFailures, ...results.filter((result) => result.status === "rejected").map((result) => result.reason)]);
+			if (failures.size) throw new AggregateError([...failures], "Studio authoring Host cleanup failed");
+		});
+		disposing.catch(() => {});
+		return disposing;
+	};
+	ctx.effect(() => dispose, "studio-authoring-host");
+	return Object.freeze({
+		forParent,
+		dispose
+	});
+}
+//#endregion
+export { createDshStudioAuthoringHost as t };

package/lib/authoring-host.d.ts

@@ -0,0 +1,5 @@
+import { a as StudioPreparedLocator, i as StudioAuthoringAddress, n as DshStudioAuthoringHostOptions, o as StudioPreparedProjection, r as DshStudioAuthoringParent, t as DshStudioAuthoringHost } from "./authoring-host.types-d5UT0WEk.js";
+//#region src/authoring-host.d.ts
+declare function createDshStudioAuthoringHost(options: DshStudioAuthoringHostOptions): Promise<DshStudioAuthoringHost>;
+//#endregion
+export { type DshStudioAuthoringHost, type DshStudioAuthoringHostOptions, type DshStudioAuthoringParent, type StudioAuthoringAddress, type StudioPreparedLocator, type StudioPreparedProjection, createDshStudioAuthoringHost };

package/lib/authoring-host.js

@@ -0,0 +1,2 @@
+import { t as createDshStudioAuthoringHost } from "./authoring-host-BlsA6wXz.js";
+export { createDshStudioAuthoringHost };

package/lib/authoring-host.types-d5UT0WEk.d.ts

@@ -0,0 +1,77 @@
+import { r as StudioAuthoringReference, t as StudioAuthoringObservation } from "./authoring-agent.types-QLa61eE6.js";
+import { a as StudioSessionRun, n as StudioAuthoringSessionOptions, o as StudioSessionStart, r as StudioSessionPrepared } from "./authoring-session.types-MHEaEFkO.js";
+import { t as DshStudioInstanceSources } from "./authoring-sources-BzRuEuub.js";
+import { Context } from "@deepseek-ai/cordis";
+import DesignService from "@yugoo-design/dsh-design-core";
+import { DesignBundleVersionPin, DesignKitVersionPin, StudioInstanceChangeRequest } from "@yugoo-design/dsh-design-studio";
+import { Agent } from "@deepseek-ai/dsh-agent";
+import { StudioInstances } from "@yugoo-design/dsh-design-studio/node";
+//#region src/authoring-content.d.ts
+type InstalledExport = {
+  readonly kind: 'kit' | 'bundle';
+  readonly pin: DesignBundleVersionPin | DesignKitVersionPin;
+  readonly provenance?: {
+    readonly source?: string;
+    readonly license?: string;
+  };
+};
+declare function createDshStudioContent({ instances }: {
+  instances: Pick<StudioInstances, 'editCurrent' | 'exportArchive'>;
+}): Promise<{
+  readArchive: ({ source }: {
+    source: string;
+  }) => Promise<import("@yugoo-design/dsh-design-studio").StudioContentArchive>;
+  exportContentArchive(input: InstalledExport | Parameters<StudioInstances["exportArchive"]>[0]): Promise<string>;
+}>;
+type DshStudioContent = Awaited<ReturnType<typeof createDshStudioContent>>;
+//#endregion
+//#region src/authoring-host.types.d.ts
+/** A locator, never a caller-supplied parent, source scope or native authority. */
+type StudioAuthoringAddress = Pick<StudioAuthoringReference, 'sessionId' | 'epoch'>;
+/** Exact browser locator; the live Host parent and S2 still supply authority. */
+interface StudioPreparedLocator {
+  readonly requestId: string;
+  readonly id: string;
+  readonly expectedRevision: number;
+  readonly digest: string;
+  readonly bundle?: DesignBundleVersionPin;
+}
+interface StudioPreparedProjection {
+  readonly locator: StudioPreparedLocator;
+  readonly prepared: StudioSessionPrepared;
+}
+interface DshStudioAuthoringHostOptions extends DshStudioInstanceSources {
+  readonly design: DshStudioInstanceSources['design'] & Pick<DesignService, 'registerCurrentKitSource' | 'listKits'>;
+  readonly ctx: Context;
+  readonly stateRoot: string;
+  readonly workspaceRoot: string;
+  readonly readComponents: StudioAuthoringSessionOptions['readComponents'];
+}
+interface DshStudioAuthoringParent {
+  /** Guarded ports over the Host's ONE shared S2 service, not private Agent records. */
+  readonly instances: StudioInstances;
+  readonly content: DshStudioContent;
+  /** Retain a bounded projection of the existing S2 preparation, without saving. */
+  prepareChanges(request: StudioInstanceChangeRequest): Promise<StudioPreparedProjection>;
+  readReference(address: StudioAuthoringAddress): Promise<StudioAuthoringReference | undefined>;
+  listReferences(): Promise<readonly StudioAuthoringReference[]>;
+  start(request: StudioSessionStart): Promise<StudioSessionRun>;
+  resume(request: StudioSessionStart & {
+    readonly previous: StudioAuthoringAddress;
+    readonly explicit: true;
+  }): Promise<StudioSessionRun>;
+  observe(address: StudioAuthoringAddress): Promise<StudioAuthoringObservation>;
+  cancel(address: StudioAuthoringAddress, options: {
+    readonly expectedTurn: number | null;
+  }): Promise<StudioAuthoringObservation>;
+  readPrepared(address: StudioAuthoringAddress | StudioPreparedLocator): Promise<StudioSessionPrepared | undefined>;
+  /** Permanently close this facade, cancel/release S4, then join admitted I/O. */
+  dispose(): Promise<void>;
+}
+interface DshStudioAuthoringHost {
+  /** Stable for the same live object; a same-ID replacement never inherits handles. */
+  forParent(parent: Agent): DshStudioAuthoringParent;
+  dispose(): Promise<void>;
+}
+//#endregion
+export { StudioPreparedLocator as a, StudioAuthoringAddress as i, DshStudioAuthoringHostOptions as n, StudioPreparedProjection as o, DshStudioAuthoringParent as r, DshStudioAuthoringHost as t };

package/lib/authoring-reference-store.d.ts

@@ -0,0 +1,39 @@
+import { r as StudioAuthoringReference } from "./authoring-agent.types-QLa61eE6.js";
+//#region src/authoring-reference-store.d.ts
+interface StudioAuthoringReferenceKey {
+  readonly parentSessionId: string;
+  readonly sessionId: string;
+  readonly epoch: string;
+}
+interface StudioAuthoringReferenceStore {
+  /** Settles after file sync, no-clobber publication and platform checks; usable as S4's callback. */
+  retain(reference: StudioAuthoringReference): Promise<void>;
+  read(key: StudioAuthoringReferenceKey): Promise<StudioAuthoringReference | undefined>;
+  /** Explicit parent only, deterministic key order, never a latest-session selector. */
+  list(input: {
+    readonly parentSessionId: string;
+  }): Promise<readonly StudioAuthoringReference[]>;
+}
+declare const STUDIO_AUTHORING_REFERENCE_LIMITS: Readonly<{
+  references: 256;
+  bytes: 524288;
+  paths: 64;
+}>;
+/** Prepare one Host-owned private leaf, without creating a store or repairing permissions.
+ * The canonical physical parent must already exist. Failures can leave the leaf;
+ * POSIX retries complete both sync barriers. Windows uses inherited user access
+ * and physical-path checks, without a directory-flush or power-loss guarantee. */
+declare function prepareStudioAuthoringDirectory(path: string): Promise<string>;
+/**
+ * Explicit private stateRoot only. The marker owns this namespace, not S2 or the
+ * root. No permission repair, stale-lock reclamation, SDK import or native action.
+ * Path/handle checks reject detected replacement; they do not sandbox arbitrary
+ * same-user mutation between filesystem syscalls. POSIX requires directory sync;
+ * Windows uses ordinary user-directory access and file publication, without a
+ * directory-flush requirement or cross-platform power-loss guarantee.
+ */
+declare function createStudioAuthoringReferenceStore(options: {
+  readonly stateRoot: string;
+}): Promise<StudioAuthoringReferenceStore>;
+//#endregion
+export { STUDIO_AUTHORING_REFERENCE_LIMITS, StudioAuthoringReferenceKey, StudioAuthoringReferenceStore, createStudioAuthoringReferenceStore, prepareStudioAuthoringDirectory };