@chatcode/chatcode-cli 3.0.3 → 3.0.4-rc.1

package/runtime/node_modules/@deepseek-ai/dsh-config-editor/lib/index.js

@@ -2,28 +2,77 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { Service, resolveConfig } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
 import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
 import yaml from "js-yaml";
-import { composeEntries, loadProfileDirectory, readProfilePatches, reconcileProfilePatches } from "@deepseek-ai/dsh-app-boot";
+import { composeEntries, loadOptionalPatches, loadProfileDirectory, readProfilePatches, reconcileProfilePatches } from "@deepseek-ai/dsh-app-boot";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { Scalar, isMap, isSeq, parseDocument, visit } from "yaml";
 //#region lib/types/index.js
-/** Profile-owned configuration edits, serialized with Loader hot reload. */
+/** Profile and shared home configuration edits, serialized with Loader hot reload. */
 function flatten(rows) {
 	return rows.flatMap((row) => [row, ...row.group && Array.isArray(row.config) ? flatten(row.config) : []]);
 }
 /** Persist complete raw configs and apply them through the normal Loader path. */
 var ConfigEditor = class extends Service {
 	ownerContext;
+	config;
 	static inject = ["loader", "profileContext"];
-	constructor(ownerContext) {
+	/** Entry ids whose configuration is shared by all profiles in the same home. */
+	static Config = z.object({ sharedEntries: z.array(String).default([]) });
+	homeFields = /* @__PURE__ */ new Map();
+	constructor(ownerContext, config) {
 		super(ownerContext, "configEditor");
 		this.ownerContext = ownerContext;
+		this.config = config;
 	}
 	/** The profile patch edited by this service. */
 	get documentPath() {
 		return this.ownerContext.profileContext.patchPath;
 	}
+	shared(entry) {
+		return this.config.sharedEntries.includes(entry.options.id) || entry.fiber !== void 0 && this.homeFields.has(entry.fiber);
+	}
+	pathFor(entry) {
+		return this.shared(entry) ? join(this.ownerContext.profileContext.home, "cordis.patch.yml") : this.documentPath;
+	}
+	/** Materialize the document that owns a namespace, or the profile patch when no namespace is given.
+	* @param namespace Registered entry id; omitted selects the profile patch.
+	* @returns Existing owning document path; missing documents are initialized under the writer lock.
+	* @throws Error when the namespace is unavailable or file preparation fails.
+	*/
+	async prepareDocument(namespace) {
+		const entry = namespace === void 0 ? void 0 : this.entries().find((candidate) => candidate.options.id === namespace);
+		if (namespace !== void 0 && entry === void 0) throw new Error(`Configuration namespace "${namespace}" is not available`);
+		const path = entry === void 0 ? this.documentPath : this.pathFor(entry);
+		await withFileLock(entry !== void 0 && this.shared(entry) ? path : join(this.ownerContext.profileContext.dir, "package.json"), async () => {
+			try {
+				await readFile(path, "utf8");
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+				await writeFileAtomic(path, "[]\n", { mode: 384 });
+			}
+		});
+		return path;
+	}
+	/** Persist selected top-level fields in the home patch shared by profiles.
+	* @param fields Plugin-owned fields to save at user scope.
+	* @param owner Activation whose Loader entry owns these fields.
+	* @returns Disposer restoring profile-scoped editing for this activation.
+	*/
+	configureHome(fields, owner) {
+		if (this.homeFields.has(owner)) throw new Error("Home fields are already configured for this plugin instance");
+		this.homeFields.set(owner, [...fields]);
+		return () => {
+			this.homeFields.delete(owner);
+		};
+	}
+	homePath() {
+		return join(this.ownerContext.profileContext.home, "cordis.patch.yml");
+	}
+	userPatches(entry, loaded) {
+		return this.shared(entry) ? loadOptionalPatches("dsh", this.homePath()) ?? [] : loaded.patches;
+	}
 	/** Addressable profile rows; nested Includes have independent configuration ownership.
 	* @returns Active entries with unique profile patch ids.
 	*/
@@ -33,7 +82,7 @@ var ConfigEditor = class extends Service {
 		for (const entry of candidates) counts.set(entry.options.id, (counts.get(entry.options.id) ?? 0) + 1);
 		return candidates.filter((entry) => counts.get(entry.options.id) === 1);
 	}
-	/** Read inherited and explicit profile values for the active entries.
+	/** Read inherited and explicit values from each entry's selected write layer.
 	* @returns Detached layer values alongside their Loader entries.
 	*/
 	configuration() {
@@ -42,17 +91,26 @@ var ConfigEditor = class extends Service {
 		return this.entries().map((entry) => ({
 			entry,
 			inherited: this.inherited(entry, loaded),
-			override: structuredClone(loaded.patches.findLast((row) => row.id === entry.options.id && row.config !== void 0)?.config ?? {})
+			override: structuredClone(this.userPatches(entry, loaded).findLast((row) => row.id === entry.options.id && row.config !== void 0)?.config ?? {})
 		}));
 	}
 	inherited(entry, loaded) {
-		const patches = loaded.patches.map((patch) => {
+		const fields = entry.fiber === void 0 ? void 0 : this.homeFields.get(entry.fiber);
+		const patches = this.userPatches(entry, loaded).map((patch) => {
 			if (patch.id !== entry.options.id || patch.insert !== void 0) return patch;
+			if (fields !== void 0) {
+				const config = { ...patch.config };
+				for (const field of fields) Reflect.deleteProperty(config, field);
+				return {
+					...patch,
+					config
+				};
+			}
 			const rest = { ...patch };
 			Reflect.deleteProperty(rest, "config");
 			return rest;
 		});
-		const row = flatten(composeEntries([...loaded.layers.map((layer) => layer.patches), patches])).find((row) => row.id === entry.options.id);
+		const row = flatten(composeEntries(this.shared(entry) ? [readProfilePatches("dsh", this.ownerContext.profileContext, loaded, patches)] : [...loaded.layers.map((layer) => layer.patches), patches])).find((row) => row.id === entry.options.id);
 		return structuredClone(row?.config ?? {});
 	}
 	/** Validate, persist, and reconcile a plugin's next config; ordinary fields keep normal lifecycle rules.
@@ -62,15 +120,23 @@ var ConfigEditor = class extends Service {
 	*/
 	async edit(entry, change) {
 		const run = async () => {
-			const path = this.documentPath;
-			await withFileLock(join(this.ownerContext.profileContext.dir, "package.json"), async () => {
+			const fields = entry.fiber === void 0 ? void 0 : this.homeFields.get(entry.fiber);
+			const shared = this.shared(entry);
+			const path = this.pathFor(entry);
+			const lockPath = shared ? this.homePath() : join(this.ownerContext.profileContext.dir, "package.json");
+			const persist = () => withFileLock(lockPath, async () => {
 				if (!this.entries().includes(entry) || entry.fiber === void 0) throw new Error("Configuration entry is no longer available");
 				const beforePatches = readProfilePatches("dsh", this.ownerContext.profileContext);
 				await reconcileProfilePatches(this.ownerContext.root, beforePatches, "dsh");
 				if (!this.entries().includes(entry)) throw new Error("Configuration entry changed during reload");
 				const current = structuredClone(entry.options.config ?? {});
-				const inherited = this.inherited(entry, loadProfileDirectory("dsh", this.ownerContext.profileContext.dir, this.ownerContext.profileContext.installAnchor));
+				const profileContext = this.ownerContext.profileContext;
+				const inherited = this.inherited(entry, loadProfileDirectory("dsh", profileContext.dir, profileContext.installAnchor));
 				const next = change(current, inherited);
+				if (fields !== void 0 && Object.keys({
+					...current,
+					...next
+				}).some((key) => !fields.includes(key) && !isDeepStrictEqual(current[key], next[key]))) throw new Error("Home-scoped edits may only change the registered fields");
 				const fiber = entry.fiber;
 				if (fiber.state !== 2) throw new Error("Configuration plugin is no longer active");
 				const resolved = fiber.ctx.waterfall(fiber, "internal/config", next, () => next);
@@ -90,7 +156,25 @@ var ConfigEditor = class extends Service {
 				if (!isSeq(document.contents)) throw new Error("Profile patch must be a YAML sequence");
 				document.contents.flow = false;
 				const index = document.contents.items.findLastIndex((item, index) => isMap(item) && document.getIn([index, "id"]) === entry.options.id && !item.has("insert") && (!item.has("name") || document.getIn([index, "name"]) === entry.options.name));
-				if (isDeepStrictEqual(next, inherited)) for (let index = document.contents.items.length - 1; index >= 0; index--) {
+				if (fields !== void 0) {
+					if (index < 0) document.add(document.createNode({
+						id: entry.options.id,
+						config: {}
+					}));
+					const target = index < 0 ? document.contents.items.length - 1 : index;
+					document.setIn([target, "mergeConfig"], true);
+					if (!isMap(document.getIn([target, "config"], true))) document.setIn([target, "config"], document.createNode({}));
+					for (const field of fields) if (Object.hasOwn(next, field)) document.setIn([
+						target,
+						"config",
+						field
+					], document.createNode(next[field]));
+					else document.deleteIn([
+						target,
+						"config",
+						field
+					]);
+				} else if (!shared && isDeepStrictEqual(next, inherited)) for (let index = document.contents.items.length - 1; index >= 0; index--) {
 					const row = document.contents.items[index];
 					if (!isMap(row) || document.getIn([index, "id"]) !== entry.options.id || row.has("insert")) continue;
 					row.delete("config");
@@ -109,9 +193,11 @@ var ConfigEditor = class extends Service {
 					return expression;
 				} });
 				const profile = this.ownerContext.profileContext;
-				const patches = readProfilePatches("dsh", profile, {
-					...loadProfileDirectory("dsh", profile.dir, profile.installAnchor),
-					patches: yaml.load(String(document), { schema: entryListSchema })
+				const loaded = loadProfileDirectory("dsh", profile.dir, profile.installAnchor);
+				const candidate = yaml.load(String(document), { schema: entryListSchema });
+				const patches = shared ? readProfilePatches("dsh", profile, loaded, candidate) : readProfilePatches("dsh", profile, {
+					...loaded,
+					patches: candidate
 				});
 				if (!isDeepStrictEqual(flatten(composeEntries([patches])).find((row) => row.id === entry.options.id)?.config ?? {}, next)) throw new Error(`Configuration for "${entry.options.id}" is overridden by a home patch or command-line overlay`);
 				await writeFileAtomic(path, String(document), { mode: 384 });
@@ -123,6 +209,8 @@ var ConfigEditor = class extends Service {
 					throw error;
 				}
 			});
+			if (this.shared(entry)) await withFileLock(join(this.ownerContext.profileContext.dir, "package.json"), persist);
+			else await persist();
 		};
 		const hmr = this.ownerContext.get("hmr");
 		await (hmr === void 0 ? run() : hmr.runExclusive(run));

package/runtime/node_modules/@deepseek-ai/dsh-config-editor/lib/types/index.d.ts

@@ -1,23 +1,53 @@
-import { Context, Service } from '@deepseek-ai/cordis';
+import { Context, Service, type Fiber } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 import type { Entry } from '@deepseek-ai/cordis-plugin-loader';
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        /** Persistent edits to the active profile's plugin configuration. */
+        /** Persistent plugin edits in profile patches or registered shared home fields. */
         configEditor: ConfigEditor;
     }
 }
+/** Entries whose complete configuration is persisted in the shared home patch. */
+export interface ConfigEditorConfig {
+    /** Entry ids whose complete configuration is shared across profiles. */
+    sharedEntries: string[];
+}
 /** Persist complete raw configs and apply them through the normal Loader path. */
 export declare class ConfigEditor extends Service {
     private readonly ownerContext;
+    private readonly config;
     static inject: string[];
-    constructor(ownerContext: Context);
+    /** Entry ids whose configuration is shared by all profiles in the same home. */
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        sharedEntries: z<string[], string[], "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        sharedEntries: z<string[], string[], "defined">;
+    }>>, "plain">;
+    private readonly homeFields;
+    constructor(ownerContext: Context, config: ConfigEditorConfig);
     /** The profile patch edited by this service. */
     get documentPath(): string;
+    private shared;
+    private pathFor;
+    /** Materialize the document that owns a namespace, or the profile patch when no namespace is given.
+     * @param namespace Registered entry id; omitted selects the profile patch.
+     * @returns Existing owning document path; missing documents are initialized under the writer lock.
+     * @throws Error when the namespace is unavailable or file preparation fails.
+     */
+    prepareDocument(namespace?: string): Promise<string>;
+    /** Persist selected top-level fields in the home patch shared by profiles.
+     * @param fields Plugin-owned fields to save at user scope.
+     * @param owner Activation whose Loader entry owns these fields.
+     * @returns Disposer restoring profile-scoped editing for this activation.
+     */
+    configureHome(fields: readonly string[], owner: Fiber): () => void;
+    private homePath;
+    private userPatches;
     /** Addressable profile rows; nested Includes have independent configuration ownership.
      * @returns Active entries with unique profile patch ids.
      */
     entries(): Entry[];
-    /** Read inherited and explicit profile values for the active entries.
+    /** Read inherited and explicit values from each entry's selected write layer.
      * @returns Detached layer values alongside their Loader entries.
      */
     configuration(): Array<{

package/runtime/node_modules/@deepseek-ai/dsh-config-editor/package.json

@@ -34,6 +34,7 @@
     "@deepseek-ai/dsh-app-boot": "workspace:*"
   },
   "dependencies": {
+    "@deepseek-ai/schemastery": "workspace:~",
     "@deepseek-ai/dsh-atomic-write": "workspace:*",
     "yaml": "^2.8.1",
     "js-yaml": "^4.1.0"

package/runtime/node_modules/@deepseek-ai/dsh-host-webserver/lib/index.js

@@ -61,8 +61,9 @@ function splice(html, at, markup) {
 * applies the table asynchronously installs it ahead of the entry module and
 * settles it after the last row; the served form below creates and resolves
 * it in one statement, because every row is already in the document text.
+* This classic script precedes browser polyfills, so it uses the base Promise API.
 */
-const READY_MARKUP = "<script>(globalThis.__DSH_BOOT_READY__ ??= Promise.withResolvers()).resolve()<\/script>";
+const READY_MARKUP = "<script>(globalThis.__DSH_BOOT_READY__ ??= { promise: Promise.resolve(), resolve() {}, reject() {} }).resolve()<\/script>";
 /**
 * Render rows into an index.html body: head rows immediately after the
 * opening head tag, body rows immediately after the opening body tag, each

package/runtime/node_modules/@deepseek-ai/dsh-native-command/lib/index.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { homedir, release, tmpdir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -44,10 +44,8 @@ const runNativeCommand = (command, args, signal) => new Promise((resolve, reject
 * The default intent prefers the default browser for documents it renders when
 * the platform can name one, then falls back to the default application. WSL
 * translates every path for the Windows desktop instead of assuming a Linux
-* GUI. The text-editor intent never consults the browser. Windows hands every
-* intent to Explorer: the shell's own default-application resolution, the one
-* a double-click uses, selects the application, while a process that resolves
-* the association itself reads a narrower record and reports none.
+* GUI. The text-editor intent never consults the browser. Windows launches
+* Notepad for text editing and delegates other intents to Explorer.
 * @module @deepseek-ai/dsh-native-command/path-opener
 */
 /** Documents a browser renders, as opposed to ones an editor merely edits. */
@@ -176,7 +174,22 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
 		return;
 	}
 	if (platform === "win32") {
-		await openWindowsPath(path, signal, run);
+		if (intent === "text-editor" && internals.run === void 0) {
+			signal.throwIfAborted();
+			await new Promise((resolve, reject) => {
+				const editor = spawn("notepad.exe", [path], {
+					detached: true,
+					stdio: "ignore",
+					windowsHide: false
+				});
+				editor.once("error", reject);
+				editor.once("spawn", () => {
+					editor.unref();
+					resolve();
+				});
+			});
+		} else if (intent === "text-editor") await run("notepad.exe", [path], signal);
+		else await openWindowsPath(path, signal, run);
 		return;
 	}
 	if (platform === "linux") {
@@ -228,8 +241,8 @@ function openNativeAssociatedPath(path, signal, internals = {}) {
 	return openNativePathWithIntent(path, signal, "association", internals);
 }
 /**
-* Open a text document for editing; macOS bypasses the file-type association
-* so a YAML association with a browser cannot consume the gesture.
+* Open a text document for editing. macOS uses the text editor; Windows launches
+* Notepad independently of file associations and RPC lifetime.
 * @param path - absolute or host-resolvable text-document path.
 * @param signal - caller/connection lifetime; abort terminates the native command.
 * @param internals - Platform and runner hooks for deterministic tests.

package/runtime/node_modules/@deepseek-ai/dsh-native-command/lib/types/path-opener.d.ts

@@ -5,10 +5,8 @@
  * The default intent prefers the default browser for documents it renders when
  * the platform can name one, then falls back to the default application. WSL
  * translates every path for the Windows desktop instead of assuming a Linux
- * GUI. The text-editor intent never consults the browser. Windows hands every
- * intent to Explorer: the shell's own default-application resolution, the one
- * a double-click uses, selects the application, while a process that resolves
- * the association itself reads a narrower record and reports none.
+ * GUI. The text-editor intent never consults the browser. Windows launches
+ * Notepad for text editing and delegates other intents to Explorer.
  * @module @deepseek-ai/dsh-native-command/path-opener
  */
 import { type NativeCommandRunner } from './runner.ts';
@@ -52,8 +50,8 @@ export declare function openNativePath(path: string, signal: AbortSignal, intern
  */
 export declare function openNativeAssociatedPath(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
 /**
- * Open a text document for editing; macOS bypasses the file-type association
- * so a YAML association with a browser cannot consume the gesture.
+ * Open a text document for editing. macOS uses the text editor; Windows launches
+ * Notepad independently of file associations and RPC lifetime.
  * @param path - absolute or host-resolvable text-document path.
  * @param signal - caller/connection lifetime; abort terminates the native command.
  * @param internals - Platform and runner hooks for deterministic tests.

package/runtime/node_modules/@deepseek-ai/dsh-native-command/lib/types/path-opener.js

@@ -5,15 +5,14 @@
  * The default intent prefers the default browser for documents it renders when
  * the platform can name one, then falls back to the default application. WSL
  * translates every path for the Windows desktop instead of assuming a Linux
- * GUI. The text-editor intent never consults the browser. Windows hands every
- * intent to Explorer: the shell's own default-application resolution, the one
- * a double-click uses, selects the application, while a process that resolves
- * the association itself reads a narrower record and reports none.
+ * GUI. The text-editor intent never consults the browser. Windows launches
+ * Notepad for text editing and delegates other intents to Explorer.
  * @module @deepseek-ai/dsh-native-command/path-opener
  */
 import { release as osRelease } from 'node:os';
 import { dirname, extname } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
 import { runNativeCommand } from "./runner.js";
 /** Documents a browser renders, as opposed to ones an editor merely edits. */
 const BROWSER_DOCUMENTS = new Set(['.html', '.htm', '.xhtml', '.svg']);
@@ -154,7 +153,19 @@ async function openNativePathWithIntent(path, signal, intent, internals = {}) {
         return;
     }
     if (platform === 'win32') {
-        await openWindowsPath(path, signal, run);
+        if (intent === 'text-editor' && internals.run === undefined) {
+            signal.throwIfAborted();
+            await new Promise((resolve, reject) => {
+                // The editor outlives the RPC. Do not wait for exit or kill an open document on disconnect.
+                const editor = spawn('notepad.exe', [path], { detached: true, stdio: 'ignore', windowsHide: false });
+                editor.once('error', reject);
+                editor.once('spawn', () => { editor.unref(); resolve(); });
+            });
+        }
+        else if (intent === 'text-editor')
+            await run('notepad.exe', [path], signal);
+        else
+            await openWindowsPath(path, signal, run);
         return;
     }
     if (platform === 'linux') {
@@ -208,8 +219,8 @@ export function openNativeAssociatedPath(path, signal, internals = {}) {
     return openNativePathWithIntent(path, signal, 'association', internals);
 }
 /**
- * Open a text document for editing; macOS bypasses the file-type association
- * so a YAML association with a browser cannot consume the gesture.
+ * Open a text document for editing. macOS uses the text editor; Windows launches
+ * Notepad independently of file associations and RPC lifetime.
  * @param path - absolute or host-resolvable text-document path.
  * @param signal - caller/connection lifetime; abort terminates the native command.
  * @param internals - Platform and runner hooks for deterministic tests.

package/runtime/node_modules/@deepseek-ai/dsh-settings/lib/index.js

@@ -402,11 +402,12 @@ var SettingsForms = class extends Service {
 	get documentPath() {
 		return this.ownerContext.configEditor.documentPath;
 	}
-	/** Locate the profile patch for native editing.
-	* @returns The existing profile patch path.
+	/** Locate and materialize the owning patch for native editing.
+	* @param namespace Optional namespace; shared entries resolve to the home-level document.
+	* @returns The existing owning patch path.
 	*/
-	prepareDocument() {
-		return Promise.resolve(this.documentPath);
+	prepareDocument(namespace) {
+		return this.ownerContext.configEditor.prepareDocument(namespace);
 	}
 	/** Read active plugin schemas and their live values.
 	* @param options Redaction required for remote callers.

package/runtime/node_modules/@deepseek-ai/dsh-settings/lib/types/index.d.ts

@@ -85,10 +85,11 @@ export declare class SettingsForms extends Service {
     get writable(): boolean;
     /** Current profile patch shown by the native configuration editor. */
     get documentPath(): string;
-    /** Locate the profile patch for native editing.
-     * @returns The existing profile patch path.
+    /** Locate and materialize the owning patch for native editing.
+     * @param namespace Optional namespace; shared entries resolve to the home-level document.
+     * @returns The existing owning patch path.
      */
-    prepareDocument(): Promise<string>;
+    prepareDocument(namespace?: string): Promise<string>;
     /** Read active plugin schemas and their live values.
      * @param options Redaction required for remote callers.
      * @returns Forms keyed by unique profile entry ids.

package/runtime/node_modules/@deepseek-ai/dsh-settings/lib/types/index.js

@@ -261,10 +261,11 @@ export class SettingsForms extends Service {
     get writable() { return true; }
     /** Current profile patch shown by the native configuration editor. */
     get documentPath() { return this.ownerContext.configEditor.documentPath; }
-    /** Locate the profile patch for native editing.
-     * @returns The existing profile patch path.
+    /** Locate and materialize the owning patch for native editing.
+     * @param namespace Optional namespace; shared entries resolve to the home-level document.
+     * @returns The existing owning patch path.
      */
-    prepareDocument() { return Promise.resolve(this.documentPath); }
+    prepareDocument(namespace) { return this.ownerContext.configEditor.prepareDocument(namespace); }
     /** Read active plugin schemas and their live values.
      * @param options Redaction required for remote callers.
      * @returns Forms keyed by unique profile entry ids.

package/runtime/node_modules/@deepseek-ai/dsh-storage/lib/types/backend.d.ts

@@ -86,6 +86,10 @@ export interface KvUnit {
         tables: Record<string, Record<string, unknown>>;
         global: unknown;
     }>;
+    /** Reload committed medium state before a domain refresh. Unsupported backends retain their snapshot. */
+    refresh?(): Promise<void>;
+    /** Hold a cross-process writer lock across a complete logical operation, including all its writes. */
+    exclusive?<T>(operation: () => Promise<T>): Promise<T>;
     /**
      * Read one record without loading other records. Backends without keyed
      * reads omit this member; on-demand domains require it.

package/runtime/node_modules/@deepseek-ai/dsh-storage-domain/lib/index.js

@@ -1,5 +1,7 @@
 import z from "@deepseek-ai/schemastery";
 import { UNIT_NAME_RE, storageBackendServiceKey } from "@deepseek-ai/dsh-storage";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isDeepStrictEqual } from "node:util";
 //#region lib/types/error.js
 /**
 * Error vocabulary of the domain data form.
@@ -109,6 +111,7 @@ const noop = () => {};
 */
 var DomainImpl = class {
 	ctx;
+	spec;
 	unit;
 	onClosed;
 	/** Domain name from the spec. */
@@ -123,6 +126,7 @@ var DomainImpl = class {
 	/** Set when close finishes (chain drained, unit closed): reads reject from here on. */
 	closed = false;
 	disposal;
+	operationScope = new AsyncLocalStorage();
 	/**
 	* @param ctx - Context that carries `domain/changed` emissions.
 	* @param spec - The domain declaration.
@@ -138,6 +142,7 @@ var DomainImpl = class {
 	*/
 	constructor(ctx, spec, unit, records, globalValue, onClosed, readStored) {
 		this.ctx = ctx;
+		this.spec = spec;
 		this.unit = unit;
 		this.onClosed = onClosed;
 		this.name = spec.name;
@@ -191,6 +196,53 @@ var DomainImpl = class {
 		if (table === void 0) throw new Error(`domain '${this.name}' declares no table '${name}'`);
 		return table;
 	}
+	/** Reload eager records atomically in memory; a malformed record leaves the previous projection untouched.
+	* @returns Whether persisted records or global values changed the in-memory projection.
+	*/
+	refresh() {
+		return this.enqueue(async () => {
+			await this.unit.refresh?.();
+			const snapshot = await this.unit.loadAll();
+			const records = /* @__PURE__ */ new Map();
+			let global;
+			try {
+				for (const [name, tableSpec] of Object.entries(this.spec.tables)) {
+					const parsed = /* @__PURE__ */ new Map();
+					for (const [key, raw] of Object.entries(snapshot.tables[name] ?? {})) parsed.set(key, tableSpec.valueSchema.parse(raw));
+					records.set(name, parsed);
+				}
+				global = this.spec.global === void 0 ? void 0 : snapshot.global === null ? this.spec.global.initial : this.spec.global.schema.parse(snapshot.global);
+			} catch (error) {
+				throw new DomainError("invalid-record", `domain '${this.name}': refreshed snapshot failed validation`, { cause: error });
+			}
+			let changed = !isDeepStrictEqual(this.globalValue, global);
+			for (const [name, next] of records) {
+				const table = this.tables.get(name);
+				if (table === void 0) throw new Error(`domain '${this.name}' declares no table '${name}'`);
+				changed = table.replace(next) || changed;
+			}
+			this.globalValue = global;
+			return changed;
+		});
+	}
+	/** Nested table/global operations run on this queue slot, not behind their own awaiting parent.
+	* @param operation Work executed under the domain queue and backend writer lock.
+	* @returns The operation result after the locked work settles.
+	*/
+	exclusive(operation) {
+		if (this.operationScope.getStore()?.active) return operation();
+		return this.enqueue(async () => {
+			const run = async () => {
+				const scope = { active: true };
+				try {
+					return await this.operationScope.run(scope, operation);
+				} finally {
+					scope.active = false;
+				}
+			};
+			return await (this.unit.exclusive === void 0 ? run() : this.unit.exclusive(run));
+		});
+	}
 	/**
 	* Close this domain: reject new writes immediately, drain already-queued
 	* writes (their events still emit), close the unit, then free the name via
@@ -221,6 +273,7 @@ var DomainImpl = class {
 		}
 	}
 	enqueue(job) {
+		if (this.operationScope.getStore()?.active) return job();
 		if (this.disposing) return Promise.reject(new DomainError("closed", `domain '${this.name}' is closed`));
 		const result = this.chain.then(job);
 		this.chain = result.then(noop, noop);
@@ -241,6 +294,13 @@ var KvTableImpl = class {
 		this.tableName = tableName;
 		this.records = records;
 	}
+	replace(next) {
+		if (isDeepStrictEqual(this.records, next)) return false;
+		this.records.clear();
+		for (const [key, value] of next) this.records.set(key, value);
+		this.loaded.clear();
+		return true;
+	}
 	read(key) {
 		return this.host.enqueue(async () => {
 			if (this.host.readStored !== void 0 && !this.loaded.has(key)) {

package/runtime/node_modules/@deepseek-ai/dsh-storage-domain/lib/types/domain.d.ts

@@ -94,6 +94,10 @@ export interface Domain<S extends DomainSpec> {
     readonly name: string;
     /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
     readonly global: DomainGlobalHandleOf<S>;
+    /** Reload and validate the complete medium snapshot. No events emit; the owner publishes its refreshed projection. */
+    refresh(): Promise<boolean>;
+    /** Serialize a logical operation locally and, where supported, across processes. Refresh inside the operation before writing. */
+    exclusive<T>(operation: () => Promise<T>): Promise<T>;
     /**
      * Resolve one declared table handle. Handles are stable — repeated calls
      * return the same instance.
@@ -135,6 +139,7 @@ export interface RecordDomain<S extends DomainSpec> {
  */
 export declare class DomainImpl {
     private readonly ctx;
+    private readonly spec;
     private readonly unit;
     private readonly onClosed;
     /** Domain name from the spec. */
@@ -149,6 +154,7 @@ export declare class DomainImpl {
     /** Set when close finishes (chain drained, unit closed): reads reject from here on. */
     private closed;
     private disposal?;
+    private readonly operationScope;
     /**
      * @param ctx - Context that carries `domain/changed` emissions.
      * @param spec - The domain declaration.
@@ -172,6 +178,15 @@ export declare class DomainImpl {
      * @returns the stable table handle.
      */
     table(name: string): KvTable<string, unknown>;
+    /** Reload eager records atomically in memory; a malformed record leaves the previous projection untouched.
+     * @returns Whether persisted records or global values changed the in-memory projection.
+     */
+    refresh(): Promise<boolean>;
+    /** Nested table/global operations run on this queue slot, not behind their own awaiting parent.
+     * @param operation Work executed under the domain queue and backend writer lock.
+     * @returns The operation result after the locked work settles.
+     */
+    exclusive<T>(operation: () => Promise<T>): Promise<T>;
     /**
      * Close this domain: reject new writes immediately, drain already-queued
      * writes (their events still emit), close the unit, then free the name via