super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/lib/fs-aware/sandbox-plugin.js

@@ -0,0 +1,249 @@
+import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-T4I0nfPM.js";
+import { stat } from "node:fs/promises";
+import { dirname, sep } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+
+//#region ../upstream/deepseek-harness/packages/fs/fs-sandbox/lib/index.js
+/**
+* Path-containment mechanics for the filesystem sandbox. Canonical spellings
+* take the fast lexical path; filesystem identity supplies the conservative
+* fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+* @module @deepseek-ai/dsh-fs-sandbox/containment
+*/
+const MISSING_CODES = new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path$1, caseSensitive) {
+	return caseSensitive ? path$1 : path$1.toLowerCase();
+}
+function isLexicallyUnder(path$1, root, caseSensitive) {
+	const comparableTarget = comparablePath(path$1, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path$1) {
+	try {
+		return await stat(path$1, { bigint: true });
+	} catch (error) {
+		/* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */
+		if (isMissing(error)) return void 0;
+		/* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path$1, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path$1, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path$1;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+/**
+* `SandboxedFileSystem`: the sandbox-enforcing implementation of the
+* `@deepseek-ai/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
+* text-storage mechanics — resolve, stat, read/stream, list, the atomic
+* write and the read-match-write edit critical section — are the local
+* implementation's, verbatim; this package adds only the per-call POLICY fence
+* on the two mutations. Reads pass through untouched: every mode permits
+* reading.
+*
+* The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+* NOT a kernel boundary — the operations are the seam's own (open, rename),
+* and only the target path is untrusted, so canonicalize-then-contain is the
+* complete answer to this surface. This is containment, not a security
+* boundary; kernel-grade isolation of untrusted CODE stays `ctx.shell`'s job
+* (`@deepseek-ai/dsh-bash-sandbox`). The residual
+* TOCTOU (an ancestor symlink swapped between the containment re-check and the
+* syscall) is narrowed by re-canonicalizing immediately before delegating and
+* is accepted for this threat model.
+*
+* Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+* a mutation only when the target canonicalizes under the policy's workspace
+* root or a platform temp area from the shared `writableRoots` policy;
+* `danger-full-access` delegates unfenced. A denial throws the structured
+* `FS_SANDBOX_DENIED`.
+*
+* @module @deepseek-ai/dsh-fs-sandbox
+*/
+/**
+* Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
+* INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
+* swap — the model-facing tools are untouched). Its configured default mode is
+* the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+* each session's mode and cwd into a policy for every mutation, while an
+* approved escalation may stamp a strictly wider mode for one call.
+*/
+var SandboxedFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy"];
+	defaultMode;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* Fence the write by the per-call policy, then delegate to the inherited
+	* atomic write. See {@link checkedTarget}.
+	* @param target - the resolved target to write.
+	* @param content - the full new file content.
+	* @param expected - the write intent guarding the write; omit for unconditional.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the write outcome from the inherited backend.
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* Fence the edit by the per-call policy, then delegate to the inherited
+	* atomic edit. See {@link checkedTarget}.
+	* @param target - the resolved target to edit.
+	* @param edit - the literal search/replace request.
+	* @param expected - the version guard; omit for an unconditional edit.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the edit outcome from the inherited backend.
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the EXACT target the
+	* mutation must use, so the checked identity is the mutated one (no
+	* check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+	* re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
+	* reflecting a concurrently swapped symlink), requires containment under a
+	* writable root, and returns THAT fresh target; `danger-full-access` returns
+	* the caller's target unfenced. Throws the structured `FS_SANDBOX_DENIED` on
+	* refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
+	* and the escalation hint.
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await this.resolve(target.displayPath);
+		let contained = false;
+		for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey, root)) {
+			contained = true;
+			break;
+		}
+		if (!contained) throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+		return fresh;
+	}
+};
+
+//#endregion
+//#region src/fs-aware/sandbox-plugin.ts
+/** Scheme prefix test — mirrors the resolver's own grammar. */
+function isSchemePath(path$1) {
+	return /^[a-z][a-z0-9]*:\/\//.test(path$1);
+}
+/** Session-layer schemes are excluded from FS-layer resolution (design D2). */
+function isSessionLayerScheme(path$1) {
+	return path$1.startsWith("ctx://") || path$1.startsWith("agent://") || path$1.startsWith("skill://");
+}
+function sessionLayerError(url) {
+	if (url.startsWith("skill://")) return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — skill discovery (which roots load, scan depth, layered scope merge) is the host skill provider's business logic and resolves only against a calling agent, which the filesystem layer does not have. Load skills with the native \`skill\` tool; grep/glob with path=skill://… keep working through the tool layer`);
+	return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — read it through the read tool (the session-layer resolver environment carries the live agent this filesystem layer does not have)`);
+}
+const Base = SandboxedFileSystem;
+var FsAwareSandboxFileSystem = class extends Base {
+	static inject = [
+		"sandboxPolicy",
+		"settings",
+		"agents"
+	];
+	resolver;
+	schemeResolution;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.schemeResolution = config?.urlSchemes !== false;
+		this.resolver = this.buildResolver(ctx);
+	}
+	/**
+	* FS-layer resolver — the SHARED builder from `wrap.ts` (design D2). One
+	* registration source for both FS consumers: this backend and the instance
+	* wrap. (A private duplicate here once drifted — a doubled `dsh` register
+	* and a literal `'http'` that would silently drop `https` if this backend
+	* were ever the outermost layer.) The `ctx`/`agent` handlers it registers
+	* are unreachable here: session-layer schemes are guarded before resolve.
+	*/
+	buildResolver(ctx) {
+		return buildFsLayerResolver({ settings: ctx.settings }, this);
+	}
+	/** FS-layer resolver env: no live agent — session-layer schemes are excluded upstream. */
+	envFor(url) {
+		return {
+			fs: this,
+			rawUrl: url
+		};
+	}
+	async resolve(path$1, opts) {
+		if (!this.schemeResolution || !isSchemePath(path$1)) return super.resolve(path$1, opts);
+		if (isSessionLayerScheme(path$1)) throw sessionLayerError(path$1);
+		await this.resolver.resolve(this.envFor(path$1), path$1);
+		return {
+			targetKey: path$1,
+			displayPath: path$1
+		};
+	}
+	async stat(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.stat(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return {
+			type: "file",
+			size: (await this.resolver.resolve(this.envFor(target.targetKey), target.targetKey)).length
+		};
+	}
+	async readText(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.readText(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return this.resolver.resolve(this.envFor(target.targetKey), target.targetKey);
+	}
+	async writeText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot write "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.writeText(target, ...rest);
+	}
+	async editText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot edit "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.editText(target, ...rest);
+	}
+};
+
+//#endregion
+export { FsAwareSandboxFileSystem as default };

package/node_modules/better-dsh/lib/hmr.d.ts

@@ -0,0 +1,32 @@
+import Hmr, { HmrConfig } from "@deepseek-ai/dsh-hmr";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/hmr.d.ts
+
+/**
+ * Native runExclusive keeps a boolean in ALS. HTTP servers created while
+ * replacing webServer inherit that boolean after the transaction finishes,
+ * so subsequent native Plugin Manager requests are refused as nested.
+ *
+ * The public runExclusive/watchConfig APIs expose no selective context reset.
+ * AsyncLocalStorage.snapshot() also resets AgentRegistry initiator attribution
+ * and its teardown lineage, so it cannot safely repair this host transaction.
+ * This compatibility bridge reads the native TS-private `executing` storage
+ * after checking its runtime shape. It never replaces that storage or changes
+ * upstream files: only exit() clears its inherited value while the unchanged
+ * native method establishes the next transaction. Native queue, closing,
+ * exact watchers, module reload and disposal retain their original semantics.
+ *
+ * The mutable token rejects nesting only while its operation is still active;
+ * resources created by that operation can initiate later transactions.
+ * A native implementation change fails initialization explicitly instead of
+ * silently dropping queue or lifecycle guarantees.
+ */
+declare class BetterHmr extends Hmr {
+  private readonly nativeTransactions;
+  private readonly liveTransactions;
+  constructor(ctx: Context, config: HmrConfig);
+  runExclusive<T>(operation: () => Promise<T>): Promise<T>;
+}
+//#endregion
+export { BetterHmr as default };

package/node_modules/better-dsh/lib/hmr.js

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import Hmr from "@deepseek-ai/dsh-hmr";
+
+//#region src/hmr.ts
+/**
+* Native runExclusive keeps a boolean in ALS. HTTP servers created while
+* replacing webServer inherit that boolean after the transaction finishes,
+* so subsequent native Plugin Manager requests are refused as nested.
+*
+* The public runExclusive/watchConfig APIs expose no selective context reset.
+* AsyncLocalStorage.snapshot() also resets AgentRegistry initiator attribution
+* and its teardown lineage, so it cannot safely repair this host transaction.
+* This compatibility bridge reads the native TS-private `executing` storage
+* after checking its runtime shape. It never replaces that storage or changes
+* upstream files: only exit() clears its inherited value while the unchanged
+* native method establishes the next transaction. Native queue, closing,
+* exact watchers, module reload and disposal retain their original semantics.
+*
+* The mutable token rejects nesting only while its operation is still active;
+* resources created by that operation can initiate later transactions.
+* A native implementation change fails initialization explicitly instead of
+* silently dropping queue or lifecycle guarantees.
+*/
+var BetterHmr = class extends Hmr {
+	nativeTransactions;
+	liveTransactions = new AsyncLocalStorage();
+	constructor(ctx, config) {
+		super(ctx, config);
+		const storage = this.executing;
+		if (!(storage instanceof AsyncLocalStorage) || typeof storage.getStore !== "function" || typeof storage.exit !== "function" || typeof storage.run !== "function") throw new Error("Better Dash HMR cannot reset this native HMR transaction context: expected executing AsyncLocalStorage");
+		this.nativeTransactions = storage;
+	}
+	runExclusive(operation) {
+		if (this.liveTransactions.getStore()?.active) return Promise.reject(/* @__PURE__ */ new Error("HMR transactions cannot be nested"));
+		return this.nativeTransactions.exit(() => super.runExclusive(() => {
+			const token = { active: true };
+			return this.liveTransactions.run(token, async () => {
+				try {
+					return await operation();
+				} finally {
+					token.active = false;
+				}
+			});
+		}));
+	}
+};
+
+//#endregion
+export { BetterHmr as default };

package/node_modules/better-dsh/lib/index-DTDXUe6m.d.ts

@@ -0,0 +1,208 @@
+import { Binary, Dict, Volatile } from "@deepseek-ai/cosmokit";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region third_party/schemastery/lib/types/index.d.ts
+declare const kSchema: unique symbol;
+declare global {
+  namespace Schemastery {
+    /** Convert primitive constructors, constants, and existing schemas into a schema type. */
+    type From<X> = X extends string | number | boolean ? Schema<X> : X extends Schema<any, any, SchemaMode> ? X : X extends typeof String ? Schema<string> : X extends typeof Number ? Schema<number> : X extends typeof Boolean ? Schema<boolean> : X extends typeof Function ? Schema<Function, (...args: any[]) => any> : X extends Constructor<infer S> ? Schema<S> : never;
+    type TypeS1<X> = X extends Schema<infer S, infer _T, infer _M> ? S : never;
+    type Inverse<X> = X extends Schema<infer _S, infer T, infer M> ? (arg: SchemaOutput<T, M>) => void : never;
+    /** Input type accepted by a schema-like value. */
+    type TypeS<X> = TypeS1<From<X>>;
+    /** Output type returned by a schema-like value after validation. */
+    type TypeT<X> = ReturnType<From<X>>;
+    /** Resolver callback used by custom schema types registered with `Schema.extend()`. */
+    type Resolve = (data: any, schema: Schema, options: Options, strict?: boolean) => [any, any?];
+    /** Input type accepted by one schema in an intersection. */
+    type IntersectS<X> = From<X> extends Schema<infer S, infer _T, infer _M> ? S : never;
+    /** Output type returned by one schema in an intersection. */
+    type IntersectT<X> = Inverse<From<X>> extends ((arg: infer T) => void) ? T : never;
+    type TupleS<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? [TypeS<L>?, ...TupleS<R>] : any[];
+    type TupleT<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? [TypeT<L>?, ...TupleT<R>] : any[];
+    type ObjectS<X extends Dict> = { [K in keyof X]?: TypeS<X[K]> | null } & Dict;
+    type ObjectT<X extends Dict> = { [K in keyof X]: TypeT<X[K]> } & Dict;
+    type Constructor<T = any> = new (...args: any[]) => T;
+    /** Static constructor and factory methods exposed by the default `Schema` export. */
+    interface Static {
+      <T = any>(options: Partial<Schema<T>>): Schema<T>;
+      new <T = any>(options: Partial<Schema<T>>): Schema<T>;
+      prototype: Schema;
+      /** Validate a value against a schema node and return `[output, adaptedInput?]`. */
+      resolve: Resolve;
+      /** Infer a schema from a primitive value, constructor, or existing schema. */
+      from<X = any>(source?: X): From<X>;
+      /** Register a resolver for a custom schema `type`. */
+      extend(type: string, resolve: Resolve): void;
+      /** Accept any value without validation. */
+      any<T = any>(): Schema<T>;
+      /** Accept only nullable input. */
+      never(): Schema<never>;
+      /** Accept exactly one constant value. */
+      const<const T>(value: T): Schema<T>;
+      /** Accept strings, with optional metadata constraints added by instance methods. */
+      string(): Schema<string>;
+      /** Accept numbers, with optional range and step constraints. */
+      number(): Schema<number>;
+      /** Accept non-negative integer numbers. */
+      natural(): Schema<number>;
+      /** Accept a number between 0 and 1 and mark it as a slider. */
+      percent(): Schema<number>;
+      /** Accept booleans. */
+      boolean(): Schema<boolean>;
+      /** Accept `Date` instances or parse datetime strings into `Date` objects. */
+      date(): Schema<string | Date, Date>;
+      /** Accept `RegExp` instances or parse strings into regular expressions. */
+      regExp(flag?: string): Schema<string | RegExp, RegExp>;
+      /** Accept binary sources and normalize them to `ArrayBufferLike`. */
+      arrayBuffer(): Schema<Binary.Source, ArrayBufferLike>;
+      arrayBuffer(encoding: 'hex' | 'base64'): Schema<Binary.Source | string, ArrayBufferLike>;
+      /** Accept a numeric bitset or string keys and normalize to a number. */
+      bitset<K extends string>(bits: Partial<Record<K, number>>): Schema<number | readonly K[], number>;
+      /** Accept functions. */
+      function(): Schema<Function, (...args: any[]) => any>;
+      /** Accept instances of a constructor or objects whose constructor name matches. */
+      is(constructor: string): Schema;
+      is<T>(constructor: Constructor<T>): Schema<T>;
+      /** Accept arrays whose elements match `inner`. */
+      array<X>(inner: X): Schema<TypeS<X>[], TypeT<X>[]>;
+      /** Accept plain objects with values matching `inner` and optional key schema. */
+      dict<X, Y extends Schema<any, string> = Schema<string>>(inner: X, sKey?: Y): Schema<Dict<TypeS<X>, TypeS<Y>>, Dict<TypeT<X>, TypeT<Y>>>;
+      /** Accept tuple arrays where each index matches the corresponding schema. */
+      tuple<const X extends readonly any[]>(list: X): Schema<TupleS<X>, TupleT<X>>;
+      /** Accept plain objects; infer fields from the dictionary, not the enclosing schema's output type. */
+      object<X extends Dict>(dict: X): Schema<ObjectS<NoInfer<X>>, ObjectT<NoInfer<X>>>;
+      /** Accept values matching at least one schema in `list`. */
+      union<const X>(list: readonly X[]): Schema<TypeS<X>, TypeT<X>>;
+      /** Accept values matching every schema in `list`, merging object outputs. */
+      intersect<const X>(list: readonly X[]): Schema<IntersectS<X>, IntersectT<X>>;
+      /** Validate with `inner`, then convert the result with `callback`. */
+      transform<X, T>(inner: X, callback: (value: TypeS<X>, options: Schemastery.Options) => T, preserve?: boolean): Schema<TypeS<X>, T>;
+      /** Defer construction of a recursive schema until validation or serialization. */
+      lazy<X extends Schema<any, any, SchemaMode>>(callback: () => X): X;
+      ValidationError: typeof ValidationError;
+    }
+    /** Runtime validation options shared by all schema calls. */
+    interface Options {
+      /** Remove invalid object properties instead of throwing when possible. */
+      autofix?: boolean;
+      /** Skip validation for selected values and schema nodes. */
+      ignore?(data: any, schema: Schema): boolean;
+      /** Path used to format nested validation errors. */
+      path?: (keyof any)[];
+    }
+    /** UI and validation metadata attached by schema builder methods. */
+    interface Meta<T = any> {
+      default?: T extends {} ? Partial<T> : T;
+      required?: boolean;
+      /** Parse this node as a stable config reference; its type and UI metadata remain unchanged. */
+      volatile?: boolean;
+      disabled?: boolean;
+      collapse?: boolean;
+      badges?: {
+        text: string;
+        type: string;
+      }[];
+      hidden?: boolean;
+      loose?: boolean;
+      role?: string;
+      extra?: any;
+      link?: string;
+      description?: string | Dict<string>;
+      comment?: string;
+      pattern?: {
+        source: string;
+        flags?: string;
+      };
+      max?: number;
+      min?: number;
+      step?: number;
+    }
+  }
+  /** Callable schema instance that validates input and returns normalized output. */
+  interface Schemastery<S = any, T = S, Mode extends SchemaMode = 'plain'> {
+    (data?: S | null, options?: Schemastery.Options): SchemaOutput<T, Mode>;
+    new (data?: S | null, options?: Schemastery.Options): SchemaOutput<T, Mode>;
+    [kSchema]: true;
+    uid: number;
+    meta: Schemastery.Meta<T>;
+    type: string;
+    sKey?: Schema;
+    inner?: Schema;
+    list?: Schema[];
+    dict?: Dict<Schema>;
+    bits?: Dict<number>;
+    callback?: Function;
+    constructor?: string | Function;
+    builder?: Function;
+    value?: T;
+    refs?: Dict<Schema>;
+    preserve?: boolean;
+    '~standard': StandardSchemaV1.Props;
+    /** Format this schema as a compact TypeScript-like type string. */
+    toString(inline?: boolean): string;
+    /** Serialize this schema, preserving shared and recursive references. */
+    toJSON(): Schema<S, T, Mode>;
+    /** Mark nullable input as invalid unless a default supplies a fallback. */
+    required<R extends boolean = true>(value?: R): Schema<S, T, SetRequired<Mode, R>>;
+    /**
+     * Parse this config field as a stable reference containing immutable data.
+     * @returns a schema whose output supports get(), including when the field is absent.
+     */
+    volatile(): Schema<NoInfer<S>, NoInfer<T>, Mode extends 'defined' | 'volatile-defined' ? 'volatile-defined' : 'volatile'>;
+    /** Hide this schema node from UI renderers. */
+    hidden(value?: boolean): Schema<S, T, Mode>;
+    /** Return the default value instead of throwing when validation fails. */
+    loose(value?: boolean): Schema<S, T, Mode>;
+    /** Attach a renderer role and optional role-specific metadata. */
+    role(text: string, extra?: any): Schema<S, T, Mode>;
+    /** Attach an external documentation link. */
+    link(link: string): Schema<S, T, Mode>;
+    /** Set the fallback value used for nullable input. */
+    default(value: T | NoInfer<Partial<S>>): Schema<S, T, SetRequired<Mode, true>>;
+    /** Attach an auxiliary comment for documentation or form UIs. */
+    comment(text: string): Schema<S, T, Mode>;
+    /** Attach a localized or plain description for documentation or form UIs. */
+    description(text: string): Schema<S, T, Mode>;
+    /** Mark this schema node as disabled for form UIs. */
+    disabled(value?: boolean): Schema<S, T, Mode>;
+    /** Request collapsed rendering for nested form UIs. */
+    collapse(value?: boolean): Schema<S, T, Mode>;
+    /** Add a deprecated badge to this schema node. */
+    deprecated(): Schema<S, T, Mode>;
+    /** Add an experimental badge to this schema node. */
+    experimental(): Schema<S, T, Mode>;
+    /** Require strings to match a regular expression. */
+    pattern(regexp: RegExp): Schema<S, T, Mode>;
+    /** Set an inclusive maximum for numbers or collection lengths. */
+    max(value: number): Schema<S, T, Mode>;
+    /** Set an inclusive minimum for numbers or collection lengths. */
+    min(value: number): Schema<S, T, Mode>;
+    /** Set the numeric increment constraint. */
+    step(value: number): Schema<S, T, Mode>;
+    /** Add or replace an object property schema. */
+    set(key: string, value: Schema): Schema<S, T, Mode>;
+    /** Append a tuple, union, or intersection member schema. */
+    push(value: Schema): Schema<S, T, Mode>;
+    /** Remove values equal to schema defaults from normalized output. */
+    simplify(value?: any): any;
+    /** Return a schema clone with descriptions merged from locale messages. */
+    i18n(messages: Dict): Schema<S, T, Mode>;
+    /** Attach arbitrary metadata consumed by form renderers and downstream tools. */
+    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T, Mode>;
+  }
+}
+declare class ValidationError extends TypeError {
+  options: Schemastery.Options;
+  name: string;
+  constructor(message: string, options: Schemastery.Options);
+  static is(error: any): error is ValidationError;
+}
+type SchemaMode = 'plain' | 'defined' | 'volatile' | 'volatile-defined';
+type SchemaOutput<T, M$1 extends SchemaMode> = M$1 extends 'volatile' ? Volatile<T | undefined> : M$1 extends 'volatile-defined' ? Volatile<T> : T;
+type SetRequired<M$1 extends SchemaMode, R extends boolean> = M$1 extends 'volatile' | 'volatile-defined' ? R extends true ? 'volatile-defined' : 'volatile' : R extends true ? 'defined' : 'plain';
+type Schema<S = any, T = S, Mode extends SchemaMode = 'plain'> = Schemastery<S, T, Mode>;
+declare const Schema: Schemastery.Static;
+//#endregion
+export { Schema as t };