@fgv/ts-json-base 5.1.0-4 → 5.1.0-40

package/dist/ts-json-base.d.ts

@@ -33,6 +33,15 @@ declare type AnyFileTreeDirectoryItem<TCT extends string = string> = IFileTreeDi
  */
 declare type AnyFileTreeFileItem<TCT extends string = string> = IFileTreeFileItem<TCT> | IMutableFileTreeFileItem<TCT>;
 
+/**
+ * Creates a schema node for a JSON `array` whose elements all match `items`.
+ * @param items - The schema applied to every element.
+ * @param opts - Optional description.
+ * @returns An `ISchemaValidator` whose `Static` type is `Array<Static<S>>`.
+ * @public
+ */
+declare function array<S extends ISchemaValidator<unknown>>(items: S, opts?: ISchemaOptions): ISchemaValidator<Static<S>[]>;
+
 /**
  * A converter which converts a supplied `unknown` value to a valid array of {@link JsonCompatibleType | JsonCompatible} values.
  * @public
@@ -72,12 +81,20 @@ declare type ArrayValidator<T, TC = unknown> = Validation.Classes.ArrayValidator
  */
 declare const boolean: Converter<boolean, IJsonConverterContext>;
 
+/**
+ * Creates a schema node for a JSON `boolean`.
+ * @param opts - Optional description.
+ * @returns An `ISchemaValidator` whose `Static` type is `boolean`.
+ * @public
+ */
+declare function boolean_2(opts?: ISchemaOptions): ISchemaValidator<boolean>;
+
 /**
  * A `BooleanValidator` which validates a boolean in place.
  * Accepts `IJsonValidatorContext` but ignores it.
  * @public
  */
-declare const boolean_2: Validator<boolean, IJsonValidatorContext>;
+declare const boolean_3: Validator<boolean, IJsonValidatorContext>;
 
 /**
  * Identifies whether some `unknown` value is a {@link JsonPrimitive | primitive},
@@ -105,6 +122,7 @@ declare namespace Converters {
     export {
         literal,
         enumeratedValue,
+        stringifiedJson,
         jsonConverter,
         IJsonConverterContext,
         jsonPrimitive,
@@ -289,6 +307,15 @@ declare function enumeratedValue<T>(values: ReadonlyArray<T>, message?: string):
  */
 declare function enumeratedValue_2<T>(values: ReadonlyArray<T>, message?: string): Validator<T, IJsonValidatorContext | ReadonlyArray<T>>;
 
+/**
+ * Creates a schema node for a closed set of string literals.
+ * @param values - The allowed string values.
+ * @param opts - Optional description.
+ * @returns An `ISchemaValidator` whose `Static` type is the union of `values`.
+ * @public
+ */
+declare function enumOf<T extends string>(values: readonly T[], opts?: ISchemaOptions): ISchemaValidator<T>;
+
 /**
  * Class representing a file in a file tree.
  * @public
@@ -345,7 +372,9 @@ declare class FileItem<TCT extends string = string> implements IMutableFileTreeF
      */
     static create<TCT extends string = string>(path: string, hal: IFileTreeAccessors<TCT>): Result<FileItem<TCT>>;
     /**
-     * {@inheritDoc FileTree.IFileTreeFileItem.getIsMutable}
+     * Indicates whether this file can be saved.
+     * @returns `DetailedSuccess` with {@link FileTree.SaveCapability} if the file can be saved,
+     * or `DetailedFailure` with {@link FileTree.SaveFailureReason} if it cannot.
      */
     getIsMutable(): DetailedResult<boolean, SaveDetail>;
     /**
@@ -366,15 +395,20 @@ declare class FileItem<TCT extends string = string> implements IMutableFileTreeF
      */
     setContentType(contentType: TCT | undefined): void;
     /**
-     * {@inheritDoc FileTree.IFileTreeFileItem.setContents}
+     * Sets the contents of the file from a JSON value.
+     * @param json - The JSON value to serialize and save.
+     * @returns `Success` if the file was saved, or `Failure` with an error message.
      */
     setContents(json: JsonValue): Result<JsonValue>;
     /**
-     * {@inheritDoc FileTree.IFileTreeFileItem.setRawContents}
+     * Sets the raw contents of the file.
+     * @param contents - The string contents to save.
+     * @returns `Success` if the file was saved, or `Failure` with an error message.
      */
     setRawContents(contents: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IFileTreeFileItem.delete}
+     * Deletes this file from its backing store.
+     * @returns `Success` with `true` if the file was deleted, or `Failure` with an error message.
      */
     delete(): Result<boolean>;
     /**
@@ -516,6 +550,27 @@ declare function forFilesystem<TCT extends string = string>(prefix?: string): Re
  */
 declare function forFilesystem<TCT extends string = string>(params?: IFileTreeInitParams<TCT>): Result<FileTree_2<TCT>>;
 
+/**
+ * Parses a raw JSON Schema object (e.g. one discovered at an MCP tool boundary) into a typed schema
+ * value within the LLM-tool subset.
+ *
+ * @remarks
+ * Because the static type cannot be recovered from a runtime value, the result is typed as the
+ * opaque supertype `ISchemaValidator<JsonValue>` — the honest type when a schema arrives at runtime,
+ * since schemas may validate strings, numbers, booleans, arrays, or objects. The `validate()` method
+ * performs real runtime validation; the derived static type is the opaque `JsonValue`.
+ *
+ * Consumers who need a narrower derived type must author the schema via the factories.
+ *
+ * Out-of-subset features fail loudly (see `FORBIDDEN_KEYWORDS`); `description` is preserved on every
+ * node; other annotations (`title`, `default`, `format`, `examples`) are silently ignored.
+ *
+ * @param json - The raw JSON Schema object to parse.
+ * @returns `Success` with the parsed schema, or `Failure` describing the first out-of-subset feature.
+ * @public
+ */
+declare function fromJson(json: JsonObject): Result<ISchemaValidator<JsonValue>>;
+
 /**
  * Implementation of {@link FileTree.IMutableFileTreeAccessors} that uses the
  * file system to access and modify files and directories.
@@ -542,55 +597,86 @@ declare class FsFileTreeAccessors<TCT extends string = string> implements IMutab
      */
     constructor(params?: IFileTreeInitParams<TCT>);
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * Resolves paths to an absolute path.
+     * @param paths - Paths to resolve.
+     * @returns The resolved absolute path.
      */
     resolveAbsolutePath(...paths: string[]): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
+     * Gets the extension of a path.
+     * @param itemPath - Path to get the extension of.
+     * @returns The extension of the path.
      */
     getExtension(itemPath: string): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
+     * Gets the base name of a path.
+     * @param itemPath - Path to get the base name of.
+     * @param suffix - Optional suffix to remove from the base name.
+     * @returns The base name of the path.
      */
     getBaseName(itemPath: string, suffix?: string): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.joinPaths}
+     * Joins paths together.
+     * @param paths - Paths to join.
+     * @returns The joined paths.
      */
     joinPaths(...paths: string[]): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getItem}
+     * Gets an item from the file tree.
+     * @param itemPath - Path of the item to get.
+     * @returns The item if it exists.
      */
     getItem(itemPath: string): Result<FileTreeItem<TCT>>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContents}
+     * Gets the contents of a file in the file tree.
+     * @param filePath - Absolute path of the file.
+     * @returns The contents of the file.
      */
     getFileContents(filePath: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
+     * Gets the content type of a file in the file tree.
+     * @param filePath - Absolute path of the file.
+     * @param provided - Optional supplied content type.
+     * @returns The content type of the file.
      */
     getFileContentType(filePath: string, provided?: string): Result<TCT | undefined>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
+     * Gets the children of a directory in the file tree.
+     * @param dirPath - Path of the directory.
+     * @returns The children of the directory.
      */
     getChildren(dirPath: string): Result<ReadonlyArray<FileTreeItem<TCT>>>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
+     * Checks if a file at the given path can be saved.
+     * @param path - The path to check.
+     * @returns `DetailedSuccess` with {@link FileTree.SaveCapability} if the file can be saved,
+     * or `DetailedFailure` with {@link FileTree.SaveFailureReason} if it cannot.
      */
     fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
+     * Saves the contents to a file at the given path.
+     * @param path - The path of the file to save.
+     * @param contents - The string contents to save.
+     * @returns `Success` if the file was saved, or `Failure` with an error message.
      */
     saveFileContents(path: string, contents: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     * Deletes a file at the given path.
+     * @param path - The path of the file to delete.
+     * @returns `Success` with `true` if the file was deleted, or `Failure` with an error message.
      */
     deleteFile(path: string): Result<boolean>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
+     * Creates a directory at the given path, including any missing parent directories.
+     * @param dirPath - The path of the directory to create.
+     * @returns `Success` with the absolute path if created, or `Failure` with an error message.
      */
     createDirectory(dirPath: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     * Deletes a directory at the given path.
+     * The directory must be empty or the operation will fail.
+     * @param dirPath - The path of the directory to delete.
+     * @returns `Success` with `true` if the directory was deleted, or `Failure` with an error message.
      */
     deleteDirectory(dirPath: string): Result<boolean>;
 }
@@ -849,6 +935,67 @@ declare interface IJsonValidatorContext {
     ignoreUndefinedProperties?: boolean;
 }
 
+/**
+ * Schema node for a JSON `array`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmArraySchema<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S>[]>;
+
+/**
+ * Schema node for a JSON `boolean`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmBooleanSchema = ISchemaValidator<boolean>;
+
+/**
+ * Schema node for a closed set of string literals (`enum`).
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmEnumSchema<T extends string> = ISchemaValidator<T>;
+
+/**
+ * Schema node for a JSON `number` or `integer`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmNumberSchema = ISchemaValidator<number>;
+
+/**
+ * Schema node for a JSON `object`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmObjectSchema<P extends ILlmProperties> = ISchemaValidator<ObjectStatic<P>>;
+
+/**
+ * Wrapper marking a property as optional within an object schema.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmOptional<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S> | undefined>;
+
+/**
+ * A record of property schemas, as accepted by the `object` factory.
+ * @public
+ */
+declare type ILlmProperties = Record<string, ISchemaValidator<unknown>>;
+
+/**
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmSchema<T> = ISchemaValidator<T>;
+
+/**
+ * Schema node for a JSON `string`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+declare type ILlmStringSchema = ISchemaValidator<string>;
+
 /**
  * Extended accessors interface that supports mutation operations.
  * All mutation methods are required — use {@link FileTree.isMutableAccessors | isMutableAccessors}
@@ -1011,60 +1158,124 @@ declare class InMemoryTreeAccessors<TCT extends string = string> implements IMut
      */
     static create<TCT extends string = string>(files: IInMemoryFile<TCT>[], params?: IFileTreeInitParams<TCT>): Result<InMemoryTreeAccessors<TCT>>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * Resolves paths to an absolute path.
+     * @param paths - Paths to resolve.
+     * @returns The resolved absolute path.
      */
     resolveAbsolutePath(...paths: string[]): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
+     * Gets the extension of a path.
+     * @param path - Path to get the extension of.
+     * @returns The extension of the path.
      */
     getExtension(path: string): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
+     * Gets the base name of a path.
+     * @param path - Path to get the base name of.
+     * @param suffix - Optional suffix to remove from the base name.
+     * @returns The base name of the path.
      */
     getBaseName(path: string, suffix?: string): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.joinPaths}
+     * Joins paths together.
+     * @param paths - Paths to join.
+     * @returns The joined paths.
      */
     joinPaths(...paths: string[]): string;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getItem}
+     * Gets an item from the file tree.
+     * @param itemPath - Path of the item to get.
+     * @returns The item if it exists.
      */
     getItem(itemPath: string): Result<FileTreeItem<TCT>>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContents}
+     * Gets the contents of a file in the file tree.
+     * @param path - Absolute path of the file.
+     * @returns The contents of the file.
      */
     getFileContents(path: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
+     * Gets the content type of a file in the file tree.
+     * @param path - Absolute path of the file.
+     * @param provided - Optional supplied content type.
+     * @returns The content type of the file.
      */
     getFileContentType(path: string, provided?: string): Result<TCT | undefined>;
     /**
-     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
+     * Gets the children of a directory in the file tree.
+     * @param path - Path of the directory.
+     * @returns The children of the directory.
      */
     getChildren(path: string): Result<ReadonlyArray<FileTreeItem<TCT>>>;
     private _addMutableFile;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
+     * Creates a directory at the given path, including any missing parent directories.
+     * @param dirPath - The path of the directory to create.
+     * @returns `Success` with the absolute path if created, or `Failure` with an error message.
      */
     createDirectory(dirPath: string): Result<string>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
+     * Checks if a file at the given path can be saved.
+     * @param path - The path to check.
+     * @returns `DetailedSuccess` with {@link FileTree.SaveCapability} if the file can be saved,
+     * or `DetailedFailure` with {@link FileTree.SaveFailureReason} if it cannot.
      */
     fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     * Deletes a file at the given path.
+     * @param path - The path of the file to delete.
+     * @returns `Success` with `true` if the file was deleted, or `Failure` with an error message.
      */
     deleteFile(path: string): Result<boolean>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     * Deletes a directory at the given path.
+     * The directory must be empty or the operation will fail.
+     * @param path - The path of the directory to delete.
+     * @returns `Success` with `true` if the directory was deleted, or `Failure` with an error message.
      */
     deleteDirectory(path: string): Result<boolean>;
     /**
-     * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
+     * Saves the contents to a file at the given path.
+     * @param path - The path of the file to save.
+     * @param contents - The string contents to save.
+     * @returns `Success` if the file was saved, or `Failure` with an error message.
      */
     saveFileContents(path: string, contents: string): Result<string>;
 }
 
+/**
+ * Creates a schema node for a JSON `integer`.
+ * @param opts - Optional description and strict mode (see `INumberSchemaOptions`).
+ * @returns An `ISchemaValidator` (tagged `integer`) whose `Static` type is `number`.
+ * @public
+ */
+declare function integer(opts?: INumberSchemaOptions): ISchemaValidator<number>;
+
+/**
+ * Options for the `number` and `integer` factories.
+ * @public
+ */
+declare interface INumberSchemaOptions extends ISchemaOptions {
+    /**
+     * When `true` (default), the derived validator rejects numeric strings such as `'42'` and
+     * accepts only genuine JSON numbers. Set `false` to opt into permissive coercion (numeric
+     * strings are accepted and converted to their numeric value).
+     */
+    strict?: boolean;
+}
+
+/**
+ * Options for the `object` factory.
+ * @public
+ */
+declare interface IObjectSchemaOptions extends ISchemaOptions {
+    /**
+     * When `false` (default), the validator rejects unrecognized properties and the emitted schema
+     * sets `additionalProperties: false`. Set `true` to allow extra fields.
+     */
+    additionalProperties?: boolean;
+}
+
 /**
  * Extended accessors interface that supports persistence operations.
  * @public
@@ -1102,6 +1313,55 @@ declare interface IReadDirectoryItem<T> {
     item: T;
 }
 
+/**
+ * Common options accepted by every schema factory.
+ * @public
+ */
+declare interface ISchemaOptions {
+    /**
+     * Optional human-readable description emitted into the wire JSON Schema.
+     */
+    description?: string;
+}
+
+/**
+ * A typed JSON Schema node for the LLM-tool subset. Every value returned by the
+ * schema factories implements this interface — it IS a `Validator<T>` and also
+ * carries a `toJson()` method for wire-format emission.
+ *
+ * @remarks
+ * The `__staticType` property is a phantom: it exists only in the type system to carry
+ * the derived static type `T` and is never assigned at runtime (declared optional so
+ * factory return values need not populate it). `Static<S>` reads this slot to recover
+ * `T` from a schema value without requiring a user-supplied type assertion. A plain
+ * optional property is used rather than a module-private `unique symbol` because this is
+ * a published package surface — a private-symbol-keyed property cannot be named in the
+ * emitted `.d.ts` (TypeBox issue #679), which would break declaration emission and API
+ * Extractor for downstream consumers.
+ *
+ * Consumers call `schema.validate(input)` directly; no separate adapter step is required.
+ * @public
+ */
+declare interface ISchemaValidator<T> extends Validator<T> {
+    /**
+     * Phantom type carrier — type-level only, never present at runtime.
+     */
+    readonly __staticType?: T;
+    /**
+     * Runtime discriminant. Identifies the schema node kind.
+     */
+    readonly _type: SchemaNodeType;
+    /**
+     * Optional human-readable description emitted into the wire JSON Schema.
+     */
+    readonly description?: string;
+    /**
+     * Emits the standard JSON Schema (draft-07 LLM-tool subset) wire form for this schema.
+     * @returns The JSON Schema object describing this schema node.
+     */
+    toJson(): JsonObject;
+}
+
 /**
  * Test if an `unknown` is potentially a {@link JsonArray | JsonArray}.
  * @param from - The `unknown` to be tested.
@@ -1455,6 +1715,64 @@ declare type JsonReplacerFunction = (key: string, value: JsonValue) => JsonValue
  */
 declare type JsonReviver = (key: string, value: JsonValue) => JsonValue;
 
+declare namespace JsonSchema {
+    export {
+        SchemaNodeType,
+        ISchemaValidator,
+        Static,
+        ILlmProperties,
+        OptionalKeys,
+        RequiredKeys,
+        OptionalPropertyStatic,
+        Simplify,
+        ObjectStatic,
+        ILlmSchema,
+        ILlmStringSchema,
+        ILlmNumberSchema,
+        ILlmBooleanSchema,
+        ILlmEnumSchema,
+        ILlmOptional,
+        ILlmArraySchema,
+        ILlmObjectSchema,
+        string_2 as string,
+        number_2 as number,
+        integer,
+        boolean_2 as boolean,
+        enumOf,
+        optional,
+        array,
+        object_3 as object,
+        ISchemaOptions,
+        INumberSchemaOptions,
+        IObjectSchemaOptions,
+        fromJson,
+        jsonSchemaConverter
+    }
+}
+export { JsonSchema }
+
+/**
+ * The main converter. Parses a raw JSON Schema object into a typed schema validator
+ * for the LLM-tool subset.
+ *
+ * @remarks
+ * Performs pre-flight checks (non-object root, union type arrays, forbidden keywords,
+ * unknown types) before dispatching to the per-type arm converters.
+ *
+ * The conversion context (`TC = string`) carries the current JSON Pointer path so that
+ * error messages from nested nodes name the actual failing node (e.g.
+ * `#/properties/config/properties/inner: 'required' key '...'`) rather than always
+ * reporting `#:`. The context defaults to `'#'` when absent (top-level call).
+ *
+ * Array and object arms reference `jsonSchemaConverter` by name from inside function
+ * declarations (hoisted). By the time any arm is called at runtime, `jsonSchemaConverter`
+ * is fully initialized, so recursive sub-schema calls also go through the pre-flight checks
+ * and produce meaningful error messages.
+ *
+ * @public
+ */
+declare const jsonSchemaConverter: Converter<ISchemaValidator<JsonValue>, string>;
+
 /**
  * Helper class to work with JSON files using FileTree API (web-compatible).
  * @public
@@ -1572,12 +1890,20 @@ declare type MutableFileTreeItem<TCT extends string = string> = IMutableFileTree
  */
 declare const number: Converter<number, IJsonConverterContext>;
 
+/**
+ * Creates a schema node for a JSON `number`.
+ * @param opts - Optional description and strict mode (see `INumberSchemaOptions`).
+ * @returns An `ISchemaValidator` whose `Static` type is `number`.
+ * @public
+ */
+declare function number_2(opts?: INumberSchemaOptions): ISchemaValidator<number>;
+
 /**
  * A `NumberValidator` which validates a number in place.
  * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
  * @public
  */
-declare const number_2: Validation.Classes.NumberValidator<number, IJsonValidatorContext>;
+declare const number_3: Validation.Classes.NumberValidator<number, IJsonValidatorContext>;
 
 /**
  * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which converts a
@@ -1599,18 +1925,62 @@ declare function object<T, TC = unknown>(properties: Conversion.FieldConverters<
  */
 declare function object_2<T, TC = unknown>(properties: Validation.Classes.FieldValidators<JsonCompatibleType<T>, TC>, params?: Omit<Validation.Classes.ObjectValidatorConstructorParams<JsonCompatibleType<T>, TC>, 'fields'>): JsonCompatible_2.ObjectValidator<T, TC>;
 
+/**
+ * Creates a schema node for a JSON `object` with a fixed set of typed properties.
+ * @param properties - A record mapping property names to their schemas. Wrap a property with
+ * `optional` to make it optional.
+ * @param opts - Optional description and `additionalProperties` flag.
+ * @returns An `ISchemaValidator` whose `Static` type derives the required/optional split.
+ * @public
+ */
+declare function object_3<P extends ILlmProperties>(properties: P, opts?: IObjectSchemaOptions): ISchemaValidator<ObjectStatic<P>>;
+
 /**
  * A converter which converts a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
  * @public
  */
 declare type ObjectConverter<T, TC = unknown> = ObjectConverter_2<JsonCompatibleType<T>, TC>;
 
+/**
+ * The derived static type for an object built from properties `P`: required keys carry their
+ * static type directly, optional keys carry theirs under a `?` modifier.
+ * @public
+ */
+declare type ObjectStatic<P extends ILlmProperties> = Simplify<{
+    [K in RequiredKeys<P>]: Static<P[K]>;
+} & {
+    [K in OptionalKeys<P>]?: OptionalPropertyStatic<P[K]>;
+}>;
+
 /**
  * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
  * @public
  */
 declare type ObjectValidator<T, TC = unknown> = Validation.Classes.ObjectValidator<JsonCompatibleType<T>, TC>;
 
+/**
+ * Marks a property schema as optional within an `object` schema.
+ * @param schema - The inner schema to make optional.
+ * @returns An `ISchemaValidator` whose `Static` type is `Static<S> | undefined`.
+ * @public
+ */
+declare function optional<S extends ISchemaValidator<unknown>>(schema: S): ISchemaValidator<Static<S> | undefined>;
+
+/**
+ * The keys of `P` whose schemas are optional (wrapped with the `optional` modifier).
+ * @public
+ */
+declare type OptionalKeys<P extends ILlmProperties> = {
+    [K in keyof P]: P[K] extends ISchemaValidator<infer U> ? (undefined extends U ? K : never) : never;
+}[keyof P];
+
+/**
+ * The static value type carried by an optional property (the inner schema's static type,
+ * without the `| undefined` that optionality adds — the `?` modifier conveys that separately).
+ * @public
+ */
+declare type OptionalPropertyStatic<V> = V extends ISchemaValidator<infer U> ? Exclude<U, undefined> : never;
+
 /**
  * Picks a nested {@link JsonObject | JsonObject} from a supplied
  * {@link JsonObject | JsonObject}.
@@ -1679,6 +2049,12 @@ declare function recordOf_2<T, TC = unknown, TK extends string = string>(validat
  */
 declare type RecordValidator<T, TC = unknown, TK extends string = string> = Validation.Validator<Record<TK, JsonCompatibleType<T>>, TC>;
 
+/**
+ * The keys of `P` whose schemas are required (i.e. not optional).
+ * @public
+ */
+declare type RequiredKeys<P extends ILlmProperties> = Exclude<keyof P, OptionalKeys<P>>;
+
 /**
  * "Sanitizes" an `unknown` by stringifying and then parsing it.  Guarantees a
  * valid {@link JsonValue | JsonValue} but is not idempotent and gives no guarantees
@@ -1725,6 +2101,31 @@ declare type SaveDetail = SaveCapability | SaveFailureReason;
  */
 declare type SaveFailureReason = 'not-supported' | 'read-only' | 'not-mutable' | 'path-excluded' | 'permission-denied';
 
+/**
+ * Discriminant tag carried by every schema node.
+ * @public
+ */
+declare type SchemaNodeType = 'string' | 'number' | 'integer' | 'boolean' | 'enum' | 'optional' | 'array' | 'object';
+
+/**
+ * Flattens an intersection of object types into a single object type for readable derived types.
+ * @public
+ */
+declare type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Recover the derived static type `T` from a schema value.
+ *
+ * @remarks
+ * `Static<typeof MySchema>` resolves to the TypeScript type that `schema.validate()` produces
+ * and that `schema.toJson()` describes — derived, never asserted. No user-supplied `T` is ever
+ * required.
+ * @public
+ */
+declare type Static<S extends ISchemaValidator<unknown>> = S extends ISchemaValidator<infer T> ? T : never;
+
 /**
  * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which converts a
  * supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
@@ -1743,12 +2144,48 @@ declare function strictObject<T, TC = unknown>(properties: Conversion.FieldConve
  */
 declare const string: StringConverter<string, IJsonConverterContext>;
 
+/**
+ * Creates a schema node for a JSON `string`.
+ * @param opts - Optional description.
+ * @returns An `ISchemaValidator` whose `Static` type is `string`.
+ * @public
+ */
+declare function string_2(opts?: ISchemaOptions): ISchemaValidator<string>;
+
 /**
  * A `StringValidator` which validates a string in place.
  * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
  * @public
  */
-declare const string_2: Validation.Classes.StringValidator<string, IJsonValidatorContext>;
+declare const string_3: Validation.Classes.StringValidator<string, IJsonValidatorContext>;
+
+/**
+ * Creates a converter that accepts a string, parses it as JSON, and optionally
+ * applies the supplied inner converter or validator to the parsed value.
+ *
+ * @remarks
+ * Unlike {@link Converters.jsonConverter}, the inner step is optional. When omitted, the
+ * converter resolves to the parsed `JsonValue` (object, array, or primitive).
+ * Both `Converter<T>` and `Validator<T>` are accepted because both expose
+ * `convert(unknown): Result<T>`.
+ *
+ * @param inner - Optional `Converter<T>` or `Validator<T>` applied to the
+ * parsed JSON value.
+ * @returns Converter that parses a JSON string into `T` (or `JsonValue` when
+ * no inner step is supplied).
+ * @public
+ */
+declare function stringifiedJson(): Converter<JsonValue>;
+
+/**
+ * Creates a converter that accepts a string, parses it as JSON, and applies
+ * the supplied inner converter or validator to the parsed value.
+ *
+ * @param inner - `Converter<T>` or `Validator<T>` applied to the parsed JSON.
+ * @returns Converter that parses a JSON string into `T`.
+ * @public
+ */
+declare function stringifiedJson<T>(inner: Converter<T> | Validator<T>): Converter<T>;
 
 /**
  * A validator which validates a supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatible} value.
@@ -1765,9 +2202,9 @@ declare namespace Validators {
         jsonObject_2 as jsonObject,
         jsonArray_2 as jsonArray,
         jsonValue_2 as jsonValue,
-        string_2 as string,
-        number_2 as number,
-        boolean_2 as boolean
+        string_3 as string,
+        number_3 as number,
+        boolean_3 as boolean
     }
 }
 export { Validators }