@artenx/dshb 0.1.7 → 0.1.9

package/lib/core/index.js

@@ -8,7 +8,7 @@ import { registerRemoteDownloadRoutes, registerWorkspaceRoutes } from "./workspa
 import { sharedWorkspaceInstructionStore } from "./workspace-instructions.js";
 import { registerWorkspaceInstructionRoutes } from "./workspace-instruction-routes.js";
 import { WorkspaceBindingsStore } from "./workspace-bindings.js";
-import { a as registerWorkspaceInstructionInjector } from "../workspace-instruction-context-CxUldQkP.js";
+import { a as registerWorkspaceInstructionInjector } from "../workspace-instruction-context-DzHFTN87.js";
 //#region src/core/index.ts
 const name = "dshb-core";
 const inject = ["webServer", "credentials"];

package/lib/core/workspace-instruction-context.d.ts

@@ -1,6 +1,36 @@
 import { SessionInstructionSnapshot, SessionInstructionSnapshotStore, WorkspaceInstructionStore } from "./workspace-instructions.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { FileAttachmentRef, ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
+//#region ../../node_modules/@deepseek-ai/dsh-brand/lib/types/index.d.ts
+/**
+ * Duplicate-install-safe nominal primitive helpers.
+ *
+ * A brand makes structurally identical strings or numbers non-interchangeable
+ * at the type level: a `SessionId` cannot be passed where a `ToolCallId` is
+ * expected, and an event sequence cannot be passed as a log offset. Comparison,
+ * logging, and serialization retain the underlying primitive behavior.
+ *
+ * This package owns no concrete domain value and keeps no runtime identity or mutable
+ * state, so independently installed copies produce interchangeable values.
+ *
+ * @module @deepseek-ai/dsh-brand
+ */
+declare const BRAND: unique symbol;
+/** A string carrying a compile-time-only brand `B`. */
+type Branded<B extends string> = string & {
+  readonly [BRAND]: B;
+};
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-typert-protocol/lib/types/owned-value.d.ts
+/** Generic invocation-owned values returned by synchronous Client Context resolvers. */
+/** Shared identity across independently bundled Context providers and Gateway. */
+declare const TYPERT_OWNED_VALUE: unique symbol;
+/** A borrowed payload paired with the invocation owner's idempotent cleanup. */
+interface TypertOwnedValue<Value> extends Disposable {
+  readonly [TYPERT_OWNED_VALUE]: true;
+  readonly value: Value;
+}
+//#endregion
 //#region ../../node_modules/@deepseek-ai/dsh-typert-protocol/lib/types/types.d.ts
 declare const LOOKUP_HOST: unique symbol;
 declare const LOOKUP_WIRE: unique symbol;
@@ -40,7 +70,21 @@ interface TypertSchema<Output = unknown> {
 type TypertCodec = {
   readonly mode: 'strict';
   readonly typeSymbol: string;
-  readonly schema: TypertSchema;
+  /** Materialize and return the process-realm schema on first boundary use. */
+  readonly create: () => TypertSchema;
+  /**
+   * Decode a unary result whose fields require type-specific handling.
+   * @param value - result reconstructed by the RPC carrier.
+   * @returns the validated result, retaining native byte views.
+   */
+  readonly decode?: (value: unknown) => unknown;
+  /**
+   * Project typed binary fields into RPC result attachments.
+   * @param value - native unary result.
+   * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
+   * @returns JSON metadata with untouched JSON subtrees retained.
+   */
+  readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown;
 } | {
   readonly mode: 'src-json';
 };
@@ -77,7 +121,7 @@ interface InvocationDescriptor {
   readonly method: string;
   /** Service member invoked when the exported method name is an alias. */
   readonly implementation?: string;
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
+  /** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
   readonly mode?: 'stream';
   /** Receiver selection mode. */
   readonly invocation: {
@@ -97,6 +141,16 @@ interface InvocationDescriptor {
   };
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[];
+  /**
+   * Client-to-Host items of the same logical stream, generated from the `In`
+   * type argument of the method's `RemoteStream<Out, In>` return type; absent
+   * when `In` is `never`. The method reads the items through
+   * `RemoteInvocation.uplink()`, so nothing enters the parameter list.
+   */
+  readonly uplink?: {
+    /** Codec validating every uplink item before `uplink()` delivers it. */
+    readonly codec: TypertCodec;
+  };
   /** Transport cancellation injected after business parameters instead of entering wire args. */
   readonly cancellation?: {
     /** Reserved final Host method parameter. */
@@ -107,6 +161,56 @@ interface InvocationDescriptor {
   /** Source declaration used only for diagnostics. */
   readonly sourceLocation?: InvocationSourceLocation;
 }
+/**
+ * Opaque identity of one Peer: a party admitted to this Host by the connection
+ * layer. "Peer" is a connection-layer word; the browser application keeps the
+ * word "Client".
+ */
+type PeerId = Branded<'PeerId'>;
+/**
+ * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * scope that owns connection-lifetime registrations and is disposed with the
+ * Peer. Who the Peer is and what it may do are not recorded here.
+ */
+interface PeerScope {
+  readonly id: PeerId;
+  readonly ctx: Context;
+  /**
+   * Tear down every registration made through `ctx`.
+   * @returns settles once the scope has quiesced; racing calls share one completion.
+   */
+  dispose(): Promise<void>;
+}
+/**
+ * The context of one Remote call, reachable inside the receiving method as
+ * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
+ * carries it, so no parameter is injected and nothing crosses the wire.
+ */
+interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string;
+    readonly method: string;
+    readonly args: Readonly<Record<string, unknown>>;
+  };
+  /** Cordis service key of the receiving Service. */
+  readonly service: string;
+  /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+  readonly peer: PeerScope;
+  /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
+  readonly signal: AbortSignal;
+  /**
+   * The Client's uplink items for this call. Available once; a second call
+   * throws. With an uplink codec on the descriptor every item is decoded to
+   * `In`; without one items arrive as `unknown` after a JSON-safety check.
+   * Iteration ends when the Client ends its uplink; when the method finishes
+   * its downlink the Gateway calls the iterator's `return()` and unread items
+   * are dropped. `In` is the caller's assertion: the runtime decodes by the
+   * descriptor and does not cross-check it.
+   * @template In - item type the caller reads; the descriptor codec decides what arrives.
+   * @returns the single-consumer uplink iterable.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>;
+}
 /** Generated Host contract selected explicitly by a Client assembly. */
 interface TypertRemoteContribution {
   /** npm package that owns the Remote methods. */
@@ -174,11 +278,11 @@ interface TypertClientContextAdapter<Wire = unknown> {
    */
   identity(ctx: Context): Wire | undefined;
   /**
-   * Resolve a wire identity from the Client's currently materialized Contexts.
+   * Resolve a validated identity synchronously for one Client invocation.
    * @param id - validated wire identity.
-   * @returns the Client Context, or `undefined` when unavailable.
+   * @returns a borrowed or invocation-owned Client Context, or undefined when unavailable.
    */
-  resolve(id: Wire): Context | undefined;
+  resolve(id: Wire): Context | TypertOwnedValue<Context> | undefined;
 }
 /** Notification emitted after a Typert runtime registry changes. */
 interface TypertRegistryChange {
@@ -320,6 +424,12 @@ interface TypertRegistryContract {
 declare module '@deepseek-ai/cordis' {
   interface Context {
     typert: TypertRegistryContract;
+    /**
+     * The Remote call this Context was derived for, or `undefined` on a
+     * Context no Remote call derived. A Service method reads it as
+     * `this.ctx.invocation`.
+     */
+    readonly invocation: RemoteInvocation | undefined;
   }
 }
 //#endregion
@@ -348,26 +458,6 @@ declare abstract class TypertRemoteService<out T = never> extends Service<T> {
   protected constructor(ctx: Context, serviceKey: string, options?: TypertGatewayBindingOptions);
 }
 //#endregion
-//#region ../../node_modules/@deepseek-ai/dsh-brand/lib/types/index.d.ts
-/**
- * Duplicate-install-safe nominal primitive helpers.
- *
- * A brand makes structurally identical strings or numbers non-interchangeable
- * at the type level: a `SessionId` cannot be passed where a `ToolCallId` is
- * expected, and an event sequence cannot be passed as a log offset. Comparison,
- * logging, and serialization retain the underlying primitive behavior.
- *
- * This package owns no concrete domain value and keeps no runtime identity or mutable
- * state, so independently installed copies produce interchangeable values.
- *
- * @module @deepseek-ai/dsh-brand
- */
-declare const BRAND: unique symbol;
-/** A string carrying a compile-time-only brand `B`. */
-type Branded<B extends string> = string & {
-  readonly [BRAND]: B;
-};
-//#endregion
 //#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/brand.d.ts
 /** Stable identity carried by one message across inbox, log, and model-request boundaries. */
 type MessageId = Branded<'MessageId'>;
@@ -407,7 +497,7 @@ declare function ReasoningEffortId(id: string): ReasoningEffortId;
 //#endregion
 //#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/message.d.ts
 /** Provider/model identity and adapter-private replay data for an assistant message. */
-interface AssistantProvenance {
+interface AssistantProviderMetadata {
   /** Provider route that produced the message. */
   provider: string;
   /** Provider model id that produced the message. */
@@ -420,81 +510,87 @@ interface AssistantProvenance {
   replayState?: unknown;
 }
 /** Required source of an assistant message produced by a routed model. */
-interface ModelMessageSource extends AssistantProvenance {
+interface ModelMessageSource extends AssistantProviderMetadata {
   kind: 'model';
 }
-/** Required source of a user-role message carrying one tool result. */
+/** Required source of a tool-role message carrying one tool result. */
 interface ToolMessageSource {
   kind: 'tool';
   callId: ToolCallId;
 }
-/** One named contribution to a `snapshot`-form context, in assembly order. */
-interface ContextSnapshotSection {
-  /** The contributing subsystem's name. */
-  readonly name: string;
-  /** That contribution's model-facing text, exactly as assembled. */
-  readonly text: string;
+/** Required source of a system-role message produced by the system-prompt plugin. */
+interface SystemPromptMessageSource {
+  kind: 'system-prompt';
 }
 /**
- * Producer-declared {@link ContextForm} and the fields that form requires,
- * mixed into the source types that carry one.
- *
- * Discriminated by `form` so a producer cannot select a form without the
- * fields needed to present it: a `notice` must record its one-line
- * account, a `snapshot` its sections. Omitting `form` stays valid — an
- * undeclared context is the documented default.
- */
-type ContextFormed = {
-  readonly form?: never;
-} | {
-  readonly form: 'instructions';
-} | {
-  readonly form: 'catalog';
-} | {
-  readonly form: 'snapshot';
-  /** The named contributions this snapshot assembled, in order. */
-  readonly sections: readonly ContextSnapshotSection[];
-} | {
-  readonly form: 'notice';
-  /** One-line account of what happened, shown without expanding the row. */
-  readonly summary: string;
-} | {
-  readonly form: 'relay';
-} | {
-  readonly form: 'recall';
-};
-/**
- * Where a message (or injected content) came from.
- * Merge-extensible sum type — plugins add their own `kind`s.
+ * Where a message (or injected content) came from, in the harness's own
+ * vocabulary. Merge-extensible sum type — each producer declares its own
+ * `kind` in its own module; there is no shared catch-all `plugin` kind.
+ * Model and tool sources answer their role messages; user messages carry any
+ * producer's kind, and consumers fall through unknown kinds.
  */
 interface MessageSourceMap {
   user: {
     kind: 'user';
   };
-  plugin: {
-    kind: 'plugin';
-    plugin: string;
-  } & ContextFormed;
   model: ModelMessageSource;
   tool: ToolMessageSource;
+  'system-prompt': SystemPromptMessageSource;
 }
 /** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
 type MessageSource = MessageSourceMap[keyof MessageSourceMap];
-/** One immutable message representation shared by delivery, durable history, and model requests. */
-interface Message {
+/** Shared immutable fields of every conversation message. */
+interface MessageBase {
   /** Stable identity preserved across every representation boundary. */
   readonly id: MessageId;
-  /** Provider-neutral conversation role. */
-  readonly role: 'system' | 'user' | 'assistant';
   /** Exact model-facing blocks. */
-  readonly content: ContentBlock[];
-  /** Required source fields supplied by the producer. */
+  readonly content: readonly ContentBlock[];
+  /** Required source fields supplied by the producer.
+   * @persistenceSource user developer
+   */
   readonly source: MessageSource;
 }
-/** A user-role specialization of the one shared message representation. */
-interface UserMessage extends Message {
+/** A rendered system prompt attributed to the system-prompt producer; empty content sends no prompt. */
+interface SystemMessage extends MessageBase {
+  readonly role: 'system';
+  readonly source: MessageSourceMap['system-prompt'];
+}
+/** Incremental agent session changes in conversation order, currently tool additions and removals. */
+interface DeveloperMessage extends MessageBase {
+  readonly role: 'developer';
+}
+/** A user-role specialization of the shared message representation. */
+interface UserMessage extends MessageBase {
   readonly role: 'user';
 }
+/** A model-produced assistant specialization of the shared message representation. */
+interface AssistantMessage extends MessageBase {
+  readonly role: 'assistant';
+  readonly source: ModelMessageSource;
+}
+/** A first-class tool-role message carrying the result of one tool invocation. */
+interface ToolResultMessage extends MessageBase {
+  readonly role: 'tool';
+  readonly source: ToolMessageSource;
+  /** Provider-issued id of the tool call this message answers. */
+  readonly toolCallId: ToolCallId;
+  /** Whether the tool invocation failed. */
+  readonly isError?: boolean;
+}
+/**
+ * The conversation messages persisted by Session, keyed by role. This map is
+ * closed because every model-visible role must have a durable Session event
+ * and an adapter projection.
+ */
+interface MessageRoleMap {
+  system: SystemMessage;
+  developer: DeveloperMessage;
+  user: UserMessage;
+  assistant: AssistantMessage;
+  tool: ToolResultMessage;
+}
+/** Any persisted conversation message, discriminated by its `role`. */
+type Message = MessageRoleMap[keyof MessageRoleMap];
 type NewUserMessage = Omit<UserMessage, 'id' | 'role'>;
 /**
  * Create one identified user-role message and freeze it before publication.
@@ -533,6 +629,13 @@ interface LlmFailure {
   readonly providerRetryAfterMs?: number;
   /** Opaque provider-issued request identifier for diagnostics. */
   readonly requestId?: ProviderRequestId;
+  /**
+   * With code `IMAGE_OFFLOAD_REQUIRED`: how many more of the oldest retained
+   * image occurrences the route needs offloaded before the same request fits
+   * its exact byte accounting. `dsh-compaction-image-offload` records the
+   * selected occurrences in an `image/offload` event and retries the step.
+   */
+  readonly offloadImages?: number;
 }
 /** Plain text visible to the end user. */
 interface TextBlock {
@@ -554,6 +657,12 @@ interface ImageBlock {
   type: 'image';
   /** Immutable bytes and intrinsic display metadata owned by the attachment service. */
   attachment: ImageAttachmentRef;
+  /**
+   * Derived from a durable image-offload decision or preserved by a message
+   * rewrite. Every route sends placeholder text naming the image and its
+   * available read-only path instead of image bytes.
+   */
+  offloaded?: true;
 }
 /**
  * A durable verbatim file reference, valid in user content. Files never reach
@@ -576,16 +685,27 @@ interface ToolCallBlock {
   /** Raw JSON string as produced by the model. */
   arguments: string;
 }
-/** The result of a tool invocation, sent back to the model. */
-interface ToolResultBlock {
-  type: 'tool-result';
-  toolCallId: ToolCallId;
-  content: ContentBlock[];
-  isError?: boolean;
+/** Activates a tool definition from the developer event's referenced request header. */
+interface ToolAdditionBlock {
+  type: 'tool-addition';
+  /** Name of exactly one tool in the referenced historical header. */
+  toolName: string;
+  /**
+   * Reserved against inline definitions; the historical request header owns the schema.
+   * @persistenceReserved
+   */
+  tool?: never;
+}
+/** Records the dynamic removal of a tool identified by its session-local name. */
+interface ToolRemovalBlock {
+  type: 'tool-removal';
+  toolName: string;
 }
 /**
  * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
+ * with adapter, UI, and compaction support. Developer tool-change blocks are
+ * reserved for Session V4 persistence; providers and UI reject them until
+ * their producers and consumers are implemented together.
  */
 interface ContentBlockMap {
   'text': TextBlock;
@@ -593,7 +713,8 @@ interface ContentBlockMap {
   'image': ImageBlock;
   'file': FileBlock;
   'tool-call': ToolCallBlock;
-  'tool-result': ToolResultBlock;
+  'tool-addition': ToolAdditionBlock;
+  'tool-removal': ToolRemovalBlock;
 }
 /** The block `type` tag vocabulary; widens as plugins add entries to {@link ContentBlockMap}. */
 type ContentBlockType = keyof ContentBlockMap;
@@ -670,10 +791,11 @@ interface LlmImageRequestPrice {
 interface LlmImageRequestPricing {
   /**
    * Price every image occurrence of one request projection.
-   * @param images - durable image references in request order, one entry per occurrence.
+   * @param images - surface image blocks in request order, one entry per occurrence; an `offloaded` block
+   *   is priced as its placeholder text.
    * @returns one price per occurrence, aligned by index with `images`.
    */
-  priceImages(images: readonly ImageAttachmentRef[]): readonly LlmImageRequestPrice[];
+  priceImages(images: readonly ImageBlock[]): readonly LlmImageRequestPrice[];
 }
 /** Display metadata for one registered provider route. */
 interface LlmProviderInfo {
@@ -766,6 +888,8 @@ interface LlmDiscoveredModel {
   contextWindow?: number;
   /** Maximum output tokens, when disclosed. */
   maxTokens?: number;
+  /** Accepted input types when disclosed by the catalog or endpoint; absent means unknown. */
+  inputModalities?: readonly ModelModality[];
 }
 /** One adapter-discovered model; catalog membership is advisory, not request validation. */
 interface LlmModelInfo {
@@ -889,11 +1013,26 @@ type StreamChunk = {
  * it from this package.
  */
 interface ToolSchema {
+  /**
+   * Requests deferred loading of the tool definition into model context,
+   * independently of whether a tool-addition block records the tool.
+   * Uses Anthropic's defer_loading terminology.
+   */
+  deferLoading?: true;
   name: string;
   description: string;
   /** JSON Schema object for the arguments. */
   parameters: Record<string, unknown>;
 }
+/** User input for one LLM request; it has no durable Session identity or source. */
+interface RequestUserInput {
+  readonly role: 'user';
+  readonly content: UserMessage['content'];
+  readonly id?: never;
+  readonly source?: never;
+}
+/** A durable conversation message or a user input used only for one request. */
+type RequestMessage = Message | RequestUserInput;
 /** A single model request, fully assembled. */
 interface GenerateOptions {
   /** Registered provider route selecting the adapter instance. */
@@ -905,9 +1044,9 @@ interface GenerateOptions {
    * Ordered conversation messages, exactly as the provider sees them. A
    * loop-built request passes the derived history (dsh-agent-loop), whose
    * leading system-role message carries the system prompt; a hand-built
-   * one-shot passes any list.
+   * one-shot may include identity-free user inputs.
    */
-  messages: Message[];
+  messages: RequestMessage[];
   /**
    * System prompt text for one-shot callers; adapters map it to the provider's
    * system slot ahead of `messages`. Loop-built requests leave it undefined.
@@ -956,6 +1095,16 @@ declare namespace Binary {
 /** String/symbol keyed dictionary type. */
 type Dict<T = any, K extends string | symbol = string> = { [key in K]: T; };
 //#endregion
+//#region ../../node_modules/@deepseek-ai/cosmokit/lib/types/volatile.d.ts
+/** Shared config references used by schema validators and plugin runtimes. */
+/** Recursively readonly data returned by a volatile config reference. */
+type VolatileSnapshot<T> = T extends object ? { readonly [K in keyof T]: VolatileSnapshot<T[K]>; } : T;
+/** A stable reference; keep the reference, or capture its value for one operation only. */
+interface Volatile<T> {
+  /** @returns the current immutable snapshot, including undefined for an absent value. */
+  get(): VolatileSnapshot<T>;
+}
+//#endregion
 //#region ../../node_modules/@standard-schema/spec/dist/index.d.ts
 /** The Standard Typed interface. This is a base type extended by other specs. */
 interface StandardTypedV1<Input = unknown, Output = Input> {
@@ -1038,9 +1187,9 @@ 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 ? 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, unknown> ? S : never;
-    type Inverse<X> = X extends Schema<any, infer Y> ? (arg: Y) => void : never;
+    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. */
@@ -1048,7 +1197,7 @@ declare global {
     /** 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, unknown> ? S : never;
+    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[];
@@ -1103,8 +1252,8 @@ declare global {
       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 whose declared properties match the schema dictionary. */
-      object<X extends Dict>(dict: X): Schema<ObjectS<X>, ObjectT<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. */
@@ -1112,7 +1261,7 @@ declare global {
       /** 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>(callback: () => X): X;
+      lazy<X extends Schema<any, any, SchemaMode>>(callback: () => X): X;
       ValidationError: typeof ValidationError;
     }
     /** Runtime validation options shared by all schema calls. */
@@ -1128,6 +1277,8 @@ declare global {
     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?: {
@@ -1151,9 +1302,9 @@ declare global {
     }
   }
   /** Callable schema instance that validates input and returns normalized output. */
-  interface Schemastery<S = any, T = S> {
-    (data?: S | null, options?: Schemastery.Options): T;
-    new (data?: S | null, options?: Schemastery.Options): T;
+  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>;
@@ -1173,49 +1324,54 @@ declare global {
     /** 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>;
+    toJSON(): Schema<S, T, Mode>;
     /** Mark nullable input as invalid unless a default supplies a fallback. */
-    required(value?: boolean): Schema<S, T>;
+    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>;
+    hidden(value?: boolean): Schema<S, T, Mode>;
     /** Return the default value instead of throwing when validation fails. */
-    loose(value?: boolean): Schema<S, T>;
+    loose(value?: boolean): Schema<S, T, Mode>;
     /** Attach a renderer role and optional role-specific metadata. */
-    role(text: string, extra?: any): Schema<S, T>;
+    role(text: string, extra?: any): Schema<S, T, Mode>;
     /** Attach an external documentation link. */
-    link(link: string): Schema<S, T>;
+    link(link: string): Schema<S, T, Mode>;
     /** Set the fallback value used for nullable input. */
-    default(value: T): Schema<S, T>;
+    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>;
+    comment(text: string): Schema<S, T, Mode>;
     /** Attach a localized or plain description for documentation or form UIs. */
-    description(text: string): Schema<S, T>;
+    description(text: string): Schema<S, T, Mode>;
     /** Mark this schema node as disabled for form UIs. */
-    disabled(value?: boolean): Schema<S, T>;
+    disabled(value?: boolean): Schema<S, T, Mode>;
     /** Request collapsed rendering for nested form UIs. */
-    collapse(value?: boolean): Schema<S, T>;
+    collapse(value?: boolean): Schema<S, T, Mode>;
     /** Add a deprecated badge to this schema node. */
-    deprecated(): Schema<S, T>;
+    deprecated(): Schema<S, T, Mode>;
     /** Add an experimental badge to this schema node. */
-    experimental(): Schema<S, T>;
+    experimental(): Schema<S, T, Mode>;
     /** Require strings to match a regular expression. */
-    pattern(regexp: RegExp): Schema<S, T>;
+    pattern(regexp: RegExp): Schema<S, T, Mode>;
     /** Set an inclusive maximum for numbers or collection lengths. */
-    max(value: number): Schema<S, T>;
+    max(value: number): Schema<S, T, Mode>;
     /** Set an inclusive minimum for numbers or collection lengths. */
-    min(value: number): Schema<S, T>;
+    min(value: number): Schema<S, T, Mode>;
     /** Set the numeric increment constraint. */
-    step(value: number): Schema<S, T>;
+    step(value: number): Schema<S, T, Mode>;
     /** Add or replace an object property schema. */
-    set(key: string, value: Schema): Schema<S, T>;
+    set(key: string, value: Schema): Schema<S, T, Mode>;
     /** Append a tuple, union, or intersection member schema. */
-    push(value: Schema): Schema<S, T>;
+    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>;
+    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>;
+    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T, Mode>;
   }
 }
 declare class ValidationError extends TypeError {
@@ -1224,7 +1380,10 @@ declare class ValidationError extends TypeError {
   constructor(message: string, options: Schemastery.Options);
   static is(error: any): error is ValidationError;
 }
-type Schema<S = any, T = S> = Schemastery<S, T>;
+type SchemaMode = 'plain' | 'defined' | 'volatile' | 'volatile-defined';
+type SchemaOutput<T, M extends SchemaMode> = M extends 'volatile' ? Volatile<T | undefined> : M extends 'volatile-defined' ? Volatile<T> : T;
+type SetRequired<M extends SchemaMode, R extends boolean> = M 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
 //#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/retry-policy.d.ts
@@ -1285,8 +1444,8 @@ declare module '@deepseek-ai/cordis' {
      *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
      *   (mutation throws): its content is a pure function of the session log (the
      *   reconstructability Agent Note), so listeners read it, never rewrite it.
-     *   Hand-built calls do not carry that marker; their messages already obey
-     *   the immutable creation contract.
+     *   Hand-built calls do not carry that marker; callers own their request
+     *   inputs and must keep them unchanged until the stream settles.
      * @mode waterfall
      */
     'llm/stream'(this: LlmRuntime, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>;