@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Type.d.ts

@@ -1,14 +1,24 @@
+/**
+ * Runtime type validation, parsing, and branded types.
+ *
+ * @module
+ */
 import type { Brand } from "./Brand.js";
 import type { RandomBytesDep } from "./Crypto.js";
-import { Result } from "./Result.js";
+import type { Result } from "./Result.js";
 import type { TimeDep } from "./Time.js";
 import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
 /**
  * Evolu {@link Type} is like a type guard that returns typed errors (via
- * {@link Result}) instead of throwing. We either get a safely typed value or a
- * composable typed error telling us exactly why validation failed.
+ * {@link Result}) instead of throwing. We either receive a safely typed value or
+ * a composable typed error that tells us exactly why the validation failed.
  *
- * Why another validation library?
+ * The reason why Evolu Type exists is that no other TypeScript validation
+ * library met Evolu's requirements. A distinctive feature of Evolu Type
+ * compared to other validation libraries is that it returns typed errors rather
+ * than string messages. This allows TypeScript to enforce that all validation
+ * errors are handled via {@link exhaustiveCheck}, significantly improving the
+ * developer experience. Those requirements are:
  *
  * - **Result-based error handling** – no exceptions for normal control flow.
  * - **Typed errors with decoupled formatters** – validation logic ≠ user
@@ -21,15 +31,10 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  *   bottom.
  * - **No user-land chaining DSL** – prepared for TC39 Hack pipes.
  *
- * A distinctive feature of Evolu Type compared to other validation libraries is
- * that it returns typed errors rather than string messages. This allows
- * TypeScript to enforce that all validation errors are handled by type
- * checking, significantly improving the developer experience.
- *
  * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
  * interoperability with 40+ validation-compatible tools and frameworks.
  *
- * ### Base Types Quick Start
+ * ## Base Types
  *
  * ```ts
  * // Validate unknown values
@@ -37,7 +42,7 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * const stringResult = String.fromUnknown(value);
  * if (!stringResult.ok) {
  *   // console.error(formatStringError(stringResult.error));
- *   return stringResult; // inside a function returning Result<string, _>
+ *   return stringResult;
  * }
  * // Safe branch: value is now string
  * const upper = stringResult.value.toUpperCase();
@@ -56,10 +61,12 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * Point.from({ x: 1, y: "2" }); // err -> nested Number error
  * ```
  *
- * ### Branding Basics
+ * ## Branded types
  *
- * Branding adds semantic meaning & constraints while preserving the runtime
- * shape:
+ * Branding is the recommended way to define types in Evolu. Instead of using
+ * primitive types like `string` or `number` directly, wrap them with
+ * {@link brand} to create semantically meaningful types. See {@link Brand} for
+ * why this matters.
  *
  * ```ts
  * const CurrencyCode = brand("CurrencyCode", String, (value) =>
@@ -83,20 +90,25 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
  * `positive`, `between`, etc.
  *
- * ### Objects & Optional Fields
+ * ## Object types
  *
  * ```ts
  * const User = object({
  *   name: NonEmptyTrimmedString100,
  *   age: optional(PositiveInt),
  * });
- * type User = typeof User.Type;
+ *
+ * // Use interface for objects. TypeScript displays the interface name
+ * // instead of expanding all properties.
+ * interface User extends InferType<typeof User> {}
  *
  * User.from({ name: "Alice" }); // ok
  * User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
+ *
+ * // TODO: Add `record`
  * ```
  *
- * ### Deriving JSON String Types
+ * ## JSON type
  *
  * ```ts
  * const Person = object({
@@ -105,7 +117,7 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  *   // To prevent this, use FiniteNumber.
  *   age: FiniteNumber,
  * });
- * type Person = typeof Person.Type;
+ * interface Person extends InferType<typeof Person> {}
  *
  * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
  *   Person,
@@ -123,7 +135,7 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * expect(personJsonToPerson(personJson)).toEqual(person);
  * ```
  *
- * ### Error Formatting
+ * ## Error Formatting
  *
  * Evolu separates validation logic from human-readable messages. There are two
  * layers:
@@ -134,14 +146,14 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  *    custom errors (including nested composite types) and lets us override
  *    selected messages.
  *
- * #### 1. Per-Type Formatter (recap)
+ * ### 1. Per-Type formatter
  *
  * ```ts
  * const r = String.fromUnknown(42);
  * if (!r.ok) console.error(formatStringError(r.error));
  * ```
  *
- * #### 2. Unified Formatter with Overrides
+ * ### 2. Unified formatter with overrides
  *
  * ```ts
  * // Override only what we care about; fall back to built-ins for the rest.
@@ -164,12 +176,14 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * tuple / union) and applies overrides only where specified, greatly reducing
  * boilerplate when formatting complex validation errors.
  *
- * ### Tip
+ * ## Naming
  *
- * If necessary, write `globalThis.String` instead of `String` to avoid naming
- * clashes with native types.
+ * Evolu Types intentionally use the same names as native JavaScript types
+ * (String, Number, Boolean, etc.). When you need to distinguish between an
+ * Evolu Type and the native type, use `globalThis` to reference the native one
+ * (e.g., `globalThis.String`, `globalThis.Number`).
  *
- * ### Design Decision: No Bidirectional Transformations
+ * ## Design decision
  *
  * Evolu Type intentionally does not support bidirectional transformations. It
  * previously did, but supporting that while keeping typed error fidelity added
@@ -178,28 +192,62 @@ import type { Literal, Refinement, Simplify, WidenLiteral } from "./Types.js";
  * reverse transforms would not buy much. We may revisit this if we can design a
  * minimal, 100% safe API that preserves simplicity.
  *
- * ### Prepared for TC39 Hack Pipes
+ * ## Composition without pipe
  *
  * Take a look how `SimplePassword` is defined:
  *
  * ```ts
- * export const SimplePassword = brand(
+ * const SimplePassword = brand(
  *   "SimplePassword",
  *   minLength(8)(maxLength(64)(TrimmedString)),
  * );
  * ```
  *
- * Nested functions are often OK (if not, make a helper) and read well, but with
- * TC39 Hack pipes it would be clearer:
+ * Shallow nesting often fits one line. If it doesn't, split into named parts:
  *
  * ```ts
- * // TrimmedString
- * //   |> minLength(8)(%)
- * //   |> maxLength(64)(%)
- * //   |> brand("SimplePassword", %)
+ * const Min8TrimmedString64 = minLength(8)(maxLength(64)(TrimmedString));
+ * const SimplePassword = brand("SimplePassword", Min8TrimmedString64);
  * ```
  *
- * Note `minLength` and `maxLength` are curried because they are factories.
+ * ## FAQ
+ *
+ * ### How do I create a generic interface like `FooState<T>`?
+ *
+ * TypeScript's {@link InferType} extracts a concrete type, not a generic one. We
+ * cannot write `interface FooState<T> extends InferType<typeof fooState<T>>`
+ * because `InferType` needs a concrete Type instance.
+ *
+ * The recommended approach is to define the generic interface manually, then
+ * create a Type factory that produces structurally compatible Types:
+ *
+ * ```ts
+ * // Define the generic interface manually
+ * interface FooState<T> {
+ *   readonly value: T;
+ *   readonly loading: boolean;
+ * }
+ *
+ * // Create a Type factory that produces Types matching the interface
+ * const fooState = <T extends AnyType>(valueType: T) =>
+ *   object({
+ *     value: valueType,
+ *     loading: Boolean,
+ *   });
+ *
+ * // Usage
+ * const StringFooState = fooState(String);
+ * type StringFooState = InferType<typeof StringFooState>;
+ *
+ * // The interface and inferred type are structurally compatible
+ * const state: FooState<string> = StringFooState.orThrow({
+ *   value: "hi",
+ *   loading: false,
+ * });
+ * ```
+ *
+ * This keeps the interface generic while having type-safe runtime validation
+ * for each concrete use.
  */
 export interface Type<Name extends TypeName, 
 /** The type this Type resolves to. */
@@ -224,6 +272,9 @@ ParentError extends TypeError = Error> extends StandardSchemaV1<Input, T> {
     /**
      * Creates `T` from an `Input` value, throwing an error if validation fails.
      *
+     * Use this where failure should crash the current flow instead of being
+     * handled locally.
+     *
      * Throws an Error with the Type validation error in its `cause` property,
      * making it debuggable while avoiding the need for custom error messages.
      *
@@ -231,36 +282,41 @@ ParentError extends TypeError = Error> extends StandardSchemaV1<Input, T> {
      *
      * **When to use:**
      *
-     * - Configuration values that are guaranteed to be valid (e.g., hardcoded
-     *   constants)
-     * - Application startup where failure should crash the program
+     * - Application startup or composition-root setup where errors must stop the
+     *   program immediately. In Evolu apps, errors are handled by
+     *   platform-specific `createRun` adapters at the app boundary.
+     * - Module-level constants
+     * - Test setup with values that are expected to be valid
      * - As an alternative to assertions when the Type error in the thrown Error's
      *   `cause` provides sufficient debugging information
-     * - Test code with known valid inputs (when error message clarity is not
-     *   critical; for better test error messages, use Vitest `schemaMatching` +
-     *   `assert` with `.is()`)
+     *
+     * Prefer `from` in ordinary application logic where the caller can recover,
+     * show validation errors, or choose a different flow.
+     *
+     * For clearer test failure messages on invalid input, use Vitest
+     * `schemaMatching` + `assert` with `.is()`.
      *
      * ### Example
      *
      * ```ts
-     * // ✅ Good: Known valid constant
+     * // Good: Known valid constant
      * const maxRetries = PositiveInt.orThrow(3);
      *
-     * // ✅ Good: App configuration that should crash on invalid values
-     * const appName = SimpleName.orThrow("MyApp");
+     * // Good: App configuration that should crash on invalid values
+     * const appName = Name.orThrow("MyApp");
      *
-     * // ✅ Good: Instead of assert when Type error is clear enough
+     * // Good: Instead of assert when Type error is clear enough
      * // Context makes it obvious: count increments from non-negative value
      * const currentCount = counts.get(id) ?? 0;
      * const newCount = PositiveInt.orThrow(currentCount + 1);
      *
-     * // ✅ Good: Test setup with known valid values
+     * // Good: Test setup with known valid values
      * const testUser = User.orThrow({ name: "Alice", age: 30 });
      *
-     * // ❌ Avoid: User input (use `from` instead)
+     * // Avoid: User input (use `from` instead)
      * const userAge = PositiveInt.orThrow(userInput); // Could crash!
      *
-     * // ✅ Better: Handle user input gracefully
+     * // Better: Handle user input gracefully
      * const ageResult = PositiveInt.from(userInput);
      * if (!ageResult.ok) {
      *   // Handle validation error
@@ -281,16 +337,16 @@ ParentError extends TypeError = Error> extends StandardSchemaV1<Input, T> {
      * ### Example
      *
      * ```ts
-     * // ✅ Good: Optional user input
+     * // Good: Optional user input
      * const age = PositiveInt.orNull(userInput);
      * if (age != null) {
      *   console.log("Valid age:", age);
      * }
      *
-     * // ✅ Good: Default fallback
+     * // Good: Default fallback
      * const maxRetries = PositiveInt.orNull(config.retries) ?? 3;
      *
-     * // ❌ Avoid: When you need to know why validation failed (use `from` instead)
+     * // Avoid: When you need to know why validation failed (use `from` instead)
      * const result = PositiveInt.from(userInput);
      * if (!result.ok) {
      *   console.error(formatPositiveError(result.error));
@@ -394,7 +450,7 @@ ParentError extends TypeError = Error> extends StandardSchemaV1<Input, T> {
 /**
  * Unique identifier for a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type TypeName = Capitalize<string>;
 export interface TypeError<Name extends TypeName = TypeName> {
@@ -413,54 +469,72 @@ export interface TypeErrorWithReason<Name extends TypeName = TypeName, Reason ex
     /** The detailed reason for the error, represented as a tagged union. */
     readonly reason: Reason;
 }
+/**
+ * A {@link Type} with all type parameters set to `any`.
+ *
+ * @group Utilities
+ */
 export type AnyType = Type<any, any, any, any, any, any>;
 /**
  * Extracts the name from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferName<A extends AnyType> = A extends Type<infer Name, any, any, any, any, any> ? Name : never;
 /**
  * Extracts the type from a {@link Type}.
  *
- * @category Utilities
+ * ### Example
+ *
+ * ```ts
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ *
+ * // Use interface for objects. TypeScript displays the interface name
+ * // instead of expanding all properties.
+ * interface User extends InferType<typeof User> {}
+ * ```
+ *
+ * @group Utilities
  */
 export type InferType<A extends AnyType> = A extends Type<any, infer T, any, any, any, any> ? T : never;
 /**
  * Extracts the input type from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferInput<A extends AnyType> = A extends Type<any, any, infer Input, any, any, any> ? Input : never;
 /**
  * Extracts the specific error type from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferError<A extends AnyType> = A extends Type<any, any, any, infer Error, any, any> ? Error : never;
 /**
  * Extracts the parent type from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferParent<A extends AnyType> = A extends Type<any, any, any, any, infer Parent, any> ? Parent : never;
 /**
  * Extracts the parent error type from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferParentError<A extends AnyType> = A extends Type<any, any, any, any, any, infer ParentError> ? ParentError : never;
 /**
  * Extracts all error types from a {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type InferErrors<T extends AnyType> = T extends Type<any, any, any, infer Error, any, infer ParentError> ? Error | ParentError : never;
 declare const EvoluTypeSymbol: unique symbol;
 /**
  * Checks if the given value is an {@link Type}.
  *
- * @category Utilities
+ * @group Utilities
  */
 export declare const isType: (value: unknown) => value is AnyType;
 /**
@@ -477,7 +551,7 @@ export declare const isType: (value: unknown) => value is AnyType;
  * );
  * ```
  *
- * @category Utilities
+ * @group Utilities
  */
 export declare const createTypeErrorFormatter: <Error extends TypeError>(format: (error: Simplify<Omit<Error, "value"> & {
     value: string;
@@ -504,7 +578,7 @@ export type TypeErrorFormatter<Error extends TypeError> = (error: Error) => stri
  * );
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const base: <Name extends TypeName, T, Error extends TypeError>(name: Name, fromUnknown: (value: unknown) => Result<T, Error>) => Type<Name, T, T, Error>;
 /**
@@ -520,50 +594,50 @@ export declare const base: <Name extends TypeName, T, Error extends TypeError>(n
  *   createBaseTypeErrorFormatter<StringError>();
  * ```
  *
- * @category Utilities
+ * @group Utilities
  */
 export declare const createBaseTypeErrorFormatter: <Error extends TypeError>() => TypeErrorFormatter<Error>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Unknown: Type<"Unknown", unknown, unknown, never, unknown, never>;
 /**
- * @category Base Types
- * @category String
+ * @group Base Types
+ * @group String
  */
 export declare const String: Type<"String", string, string, StringError, string, StringError>;
 export interface StringError extends TypeError<"String"> {
 }
 export declare const formatStringError: TypeErrorFormatter<StringError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Number: Type<"Number", number, number, NumberError, number, NumberError>;
 export interface NumberError extends TypeError<"Number"> {
 }
 export declare const formatNumberError: TypeErrorFormatter<NumberError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const BigInt: Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>;
 export interface BigIntError extends TypeError<"BigInt"> {
 }
 export declare const formatBigIntError: TypeErrorFormatter<BigIntError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Boolean: Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>;
 export interface BooleanError extends TypeError<"Boolean"> {
 }
 export declare const formatBooleanError: TypeErrorFormatter<BooleanError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Undefined: Type<"Undefined", undefined, undefined, UndefinedError, undefined, UndefinedError>;
 export interface UndefinedError extends TypeError<"Undefined"> {
 }
 export declare const formatUndefinedError: TypeErrorFormatter<UndefinedError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Null: Type<"Null", null, null, NullError, null, NullError>;
 export interface NullError extends TypeError<"Null"> {
 }
 export declare const formatNullError: TypeErrorFormatter<NullError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Function: Type<"Function", Function, Function, FunctionError, Function, FunctionError>;
 export interface FunctionError extends TypeError<"Function"> {
 }
 export declare const formatFunctionError: TypeErrorFormatter<FunctionError>;
-/** @category Base Types */
+/** @group Base Types */
 export declare const Uint8Array: Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, Uint8ArrayError, Uint8Array<ArrayBufferLike>, Uint8ArrayError>;
 export interface Uint8ArrayError extends TypeError<"Uint8Array"> {
 }
@@ -586,7 +660,7 @@ export declare const formatUint8ArrayError: TypeErrorFormatter<Uint8ArrayError>;
  * const error = UserInstance.from({}); // err
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const instanceOf: <T extends abstract new (...args: any) => any>(ctor: T) => InstanceOfType<T>;
 export interface InstanceOfError extends TypeError<"InstanceOf"> {
@@ -599,7 +673,7 @@ export declare const formatInstanceOfError: TypeErrorFormatter<InstanceOfError>;
 /**
  * JavaScript Date.
  *
- * @category Base Types
+ * @group Base Types
  */
 export declare const Date: InstanceOfType<DateConstructor>;
 /**
@@ -620,12 +694,16 @@ export declare const formatIsTypeError: TypeErrorFormatter<EvoluTypeError>;
 /**
  * Branded {@link Type}.
  *
+ * Branding is the recommended way to define types in Evolu. Instead of using
+ * primitive types like `string` or `number` directly, wrap them with `brand` to
+ * create semantically meaningful types. See {@link Brand} for why this matters.
+ *
  * The `brand` Type Factory takes the name of a new {@link Brand}, a parent Type
  * to be branded, and the optional `refine` function for additional constraint.
  *
  * The `refine` function can be omitted if we only want to add a brand.
  *
- * ### Examples
+ * ### Example
  *
  * A simple `CurrencyCode` Type:
  *
@@ -744,9 +822,10 @@ export declare const formatIsTypeError: TypeErrorFormatter<EvoluTypeError>;
  * );
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare function brand<Name extends TypeName, ParentType extends AnyType, Parent = InferType<ParentType>, RefineError extends TypeError = never>(name: Name, parent: ParentType, refine: (value: Parent) => Result<Parent, RefineError>): BrandType<ParentType, Name, RefineError, InferErrors<ParentType>>;
+/** Without refine function. */
 export declare function brand<Name extends TypeName, ParentType extends AnyType>(name: Name, parent: ParentType): BrandType<ParentType, Name, BrandWithoutRefineError<Name, InferErrors<ParentType>>>;
 export interface BrandType<ParentType extends AnyType, Name extends TypeName, Error extends TypeError = never, ParentError extends TypeError = never> extends Type<"Brand", InferType<ParentType> & Brand<Name>, InferInput<ParentType>, Error, InferType<ParentType>, ParentError> {
     readonly brand: Name;
@@ -758,7 +837,7 @@ export interface BrandWithoutRefineError<Name extends TypeName, ParentError exte
 /**
  * A three-letter ISO 4217 currency code (e.g., USD, EUR).
  *
- * @category String
+ * @group String
  */
 export declare const CurrencyCode: BrandType<Type<"String", string, string, StringError, string, StringError>, "CurrencyCode", CurrencyCodeError, StringError>;
 export type CurrencyCode = typeof CurrencyCode.Type;
@@ -784,7 +863,7 @@ export declare const formatCurrencyCodeError: TypeErrorFormatter<CurrencyCodeErr
  * const error = DateIso.from("10000-01-01T00:00:00.000Z"); // err
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const DateIso: BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoError, StringError>;
 export type DateIso = typeof DateIso.Type;
@@ -809,7 +888,18 @@ export declare const dateIsoToDate: (value: DateIso) => Date;
  *   );
  * ```
  *
- * @category Utilities
+ * ### Numeric literal inference
+ *
+ * When using factories with numeric parameters (like `lessThan`, `maxLength`,
+ * `between`), use numeric literals instead of expressions. TypeScript widens
+ * expressions to `number`, losing the literal type in the brand name:
+ *
+ * ```ts
+ * lessThan(100)(Number); // Brand<"LessThan100"> ✓
+ * lessThan(100 - 1)(Number); // Brand<"LessThan" + number> ✗
+ * ```
+ *
+ * @group Utilities
  */
 export type BrandFactory<Name extends TypeName, Input, RefineError extends TypeError> = <PName extends TypeName, P extends Input, PInput, PParent, PError extends TypeError = never, PParentError extends TypeError = never>(parent: Type<PName, P, PInput, PError, PParent, PParentError>) => BrandType<Type<PName, P, PInput, PError, PParent, PParentError>, Name, RefineError, PError | PParentError>;
 /**
@@ -826,7 +916,7 @@ export type BrandFactory<Name extends TypeName, Input, RefineError extends TypeE
  * type TrimmedNonEmptyString = typeof TrimmedNonEmptyString.Type;
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const trimmed: BrandFactory<"Trimmed", string, TrimmedError>;
 export interface TrimmedError extends TypeError<"Trimmed"> {
@@ -838,7 +928,7 @@ export declare const formatTrimmedError: TypeErrorFormatter<TrimmedError>;
  * - Use `TrimmedString.is` to check if an unknown value is trimmed.
  * - Use `TrimmedString.from` to check if a string is trimmed.
  *
- * @category String
+ * @group String
  */
 export declare const TrimmedString: BrandType<Type<"String", string, string, StringError, string, StringError>, "Trimmed", TrimmedError, StringError>;
 export type TrimmedString = typeof TrimmedString.Type;
@@ -846,6 +936,8 @@ export declare const trim: (value: string) => TrimmedString;
 /**
  * Minimum length.
  *
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
  * ### Example
  *
  * ```ts
@@ -853,8 +945,8 @@ export declare const trim: (value: string) => TrimmedString;
  * const NonEmptyString = minLength(1)(String);
  * ```
  *
- * @category String
- * @category Array
+ * @group String
+ * @group Array
  */
 export declare const minLength: <Min extends number>(min: Min) => BrandFactory<`MinLength${Min}`, {
     length: number;
@@ -866,6 +958,8 @@ export declare const formatMinLengthError: TypeErrorFormatter<MinLengthError<num
 /**
  * Maximum length.
  *
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
  * ### Example
  *
  * ```ts
@@ -873,8 +967,8 @@ export declare const formatMinLengthError: TypeErrorFormatter<MinLengthError<num
  * const String100 = maxLength(100)(String);
  * ```
  *
- * @category String
- * @category Array
+ * @group String
+ * @group Array
  */
 export declare const maxLength: <Max extends number>(max: Max) => BrandFactory<`MaxLength${Max}`, {
     length: number;
@@ -886,6 +980,8 @@ export declare const formatMaxLengthError: TypeErrorFormatter<MaxLengthError<num
 /**
  * Exact length.
  *
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
  * ### Example
  *
  * ```ts
@@ -893,8 +989,8 @@ export declare const formatMaxLengthError: TypeErrorFormatter<MaxLengthError<num
  * const Length1String = length(1)(String);
  * ```
  *
- * @category String
- * @category Array
+ * @group String
+ * @group Array
  */
 export declare const length: <Exact extends number>(exact: Exact) => BrandFactory<`Length${Exact}`, {
     length: number;
@@ -903,34 +999,34 @@ export interface LengthError<Exact extends number = number> extends TypeError<"L
     readonly exact: Exact;
 }
 export declare const formatLengthError: TypeErrorFormatter<LengthError<number>>;
-/** @category String */
+/** @group String */
 export declare const NonEmptyString: BrandType<Type<"String", string, string, StringError, string, StringError>, "MinLength1", MinLengthError<1>, StringError>;
 export type NonEmptyString = typeof NonEmptyString.Type;
-/** @category String */
+/** @group String */
 export declare const String100: BrandType<Type<"String", string, string, StringError, string, StringError>, "MaxLength100", MaxLengthError<100>, StringError>;
 export type String100 = typeof String100.Type;
-/** @category String */
+/** @group String */
 export declare const String1000: BrandType<Type<"String", string, string, StringError, string, StringError>, "MaxLength1000", MaxLengthError<1000>, StringError>;
 export type String1000 = typeof String1000.Type;
-/** @category String */
+/** @group String */
 export declare const NonEmptyString100: BrandType<Type<"Brand", string & Brand<"MaxLength100">, string, MaxLengthError<100>, string, StringError>, "MinLength1", MinLengthError<1>, StringError | MaxLengthError<100>>;
 export type NonEmptyString100 = typeof NonEmptyString100.Type;
-/** @category String */
+/** @group String */
 export declare const NonEmptyString1000: BrandType<Type<"Brand", string & Brand<"MaxLength1000">, string, MaxLengthError<1000>, string, StringError>, "MinLength1", MinLengthError<1>, StringError | MaxLengthError<1000>>;
 export type NonEmptyString1000 = typeof NonEmptyString1000.Type;
-/** @category String */
+/** @group String */
 export declare const NonEmptyTrimmedString: BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>;
 export type NonEmptyTrimmedString = typeof NonEmptyTrimmedString.Type;
-/** @category String */
+/** @group String */
 export declare const TrimmedString100: BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MaxLength100", MaxLengthError<100>, StringError | TrimmedError>;
 export type TrimmedString100 = typeof TrimmedString100.Type;
-/** @category String */
+/** @group String */
 export declare const TrimmedString1000: BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MaxLength1000", MaxLengthError<1000>, StringError | TrimmedError>;
 export type TrimmedString1000 = typeof TrimmedString1000.Type;
-/** @category String */
+/** @group String */
 export declare const NonEmptyTrimmedString100: BrandType<Type<"Brand", string & Brand<"Trimmed"> & Brand<"MaxLength100">, string, MaxLengthError<100>, string & Brand<"Trimmed">, StringError | TrimmedError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError | MaxLengthError<100>>;
 export type NonEmptyTrimmedString100 = typeof NonEmptyTrimmedString100.Type;
-/** @category String */
+/** @group String */
 export declare const NonEmptyTrimmedString1000: BrandType<Type<"Brand", string & Brand<"Trimmed"> & Brand<"MaxLength1000">, string, MaxLengthError<1000>, string & Brand<"Trimmed">, StringError | TrimmedError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError | MaxLengthError<1000>>;
 export type NonEmptyTrimmedString1000 = typeof NonEmptyTrimmedString1000.Type;
 /**
@@ -940,7 +1036,7 @@ export type NonEmptyTrimmedString1000 = typeof NonEmptyTrimmedString1000.Type;
  * safely on the user's device using cryptographically secure random number
  * generation, ensuring it remains private and unique.
  *
- * @category String
+ * @group String
  */
 export declare const Mnemonic: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, "Mnemonic", MnemonicError, StringError | TrimmedError | MinLengthError<1>>;
 export type Mnemonic = typeof Mnemonic.Type;
@@ -956,7 +1052,7 @@ export declare const formatMnemonicError: TypeErrorFormatter<MnemonicError>;
  * const Alphanumeric = regex("Alphanumeric", /^[a-z0-9]+$/i)(String);
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const regex: <Name extends TypeName>(name: Name, pattern: RegExp) => BrandFactory<Name, string, RegexError<Name>>;
 export interface RegexError<Name extends TypeName = TypeName> extends TypeError<"Regex"> {
@@ -989,7 +1085,7 @@ export declare const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<
  * }
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const UrlSafeString: BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>;
 export type UrlSafeString = typeof UrlSafeString.Type;
@@ -1000,7 +1096,7 @@ export type UrlSafeStringError = typeof UrlSafeString.Error;
  * Encode with {@link uint8ArrayToBase64Url}, decode with
  * {@link base64UrlToUint8Array}.
  *
- * @category String
+ * @group String
  */
 export declare const Base64Url: BrandType<Type<"String", string, string, StringError, string, StringError>, "Base64Url", Base64UrlError, StringError>;
 export type Base64Url = typeof Base64Url.Type;
@@ -1012,30 +1108,31 @@ export declare const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url;
 /** Decodes a {@link Base64Url} string to a Uint8Array. */
 export declare const base64UrlToUint8Array: (str: Base64Url) => Uint8Array;
 /**
- * Simple alphanumeric string for naming in file systems, URLs, and identifiers.
+ * Alphanumeric string for naming in file systems, URLs, and identifiers.
  *
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
- * `_`). See `UrlSafeString` for details.
+ * `_`).
  *
  * The string must be between 1 and 64 characters.
  *
  * ### Example
  *
  * ```ts
- * const result = SimpleName.from("data-report-123");
+ * const result = Name.from("data-report-123");
  * if (result.ok) {
- *   console.log("Valid SimpleName string:", result.value);
+ *   console.log("Valid Name string:", result.value);
  * } else {
- *   console.error("Invalid SimpleName string:", result.error);
+ *   console.error("Invalid Name string:", result.error);
  * }
  * ```
  *
- * @category String
+ * @group String
  */
-export declare const SimpleName: BrandType<BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>, "SimpleName", SimpleNameError, StringError | RegexError<"UrlSafeString">>;
-export type SimpleName = typeof SimpleName.Type;
-export interface SimpleNameError extends TypeError<"SimpleName"> {
+export declare const Name: BrandType<BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>, "Name", NameError, StringError | RegexError<"UrlSafeString">>;
+export type Name = typeof Name.Type;
+export interface NameError extends TypeError<"Name"> {
 }
+export declare const testName: string & Brand<"UrlSafeString"> & Brand<"Name">;
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
@@ -1058,7 +1155,7 @@ export interface SimpleNameError extends TypeError<"SimpleName"> {
  * //   |> brand("SimplePassword", %)
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const SimplePassword: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed"> & Brand<"MaxLength64">, string, MaxLengthError<64>, string & Brand<"Trimmed">, StringError | TrimmedError>, "MinLength8", MinLengthError<8>, StringError | TrimmedError | MaxLengthError<64>>, "SimplePassword", BrandWithoutRefineError<"SimplePassword", StringError | TrimmedError | MinLengthError<8> | MaxLengthError<64>>, never>;
 export type SimplePassword = typeof SimplePassword.Type;
@@ -1080,14 +1177,14 @@ export declare const formatSimplePasswordError: (formatTypeError: TypeErrorForma
  * copied (logs, URLs, exports); only use it when you explicitly want insertion
  * locality for very large write‑heavy tables and accept timestamp exposure.
  *
- * ### Future
+ * ## Future
  *
  * A possible hybrid masked‑time approach (`timestamp ^ H(cluster_id, timestamp
  *
  * > > N)`) could provide locality without exposing raw creation time. See
  * > > https://brooker.co.za/blog/2025/10/22/uuidv7.html
  *
- * @category String
+ * @group String
  */
 export declare const Id: BrandType<Type<"String", string, string, StringError, string, StringError>, "Id", IdError, StringError>;
 export type Id = typeof Id.Type;
@@ -1139,7 +1236,7 @@ export declare const createId: <B extends string = never>(deps: RandomBytesDep)
  * external string from the generated {@link Id}. If you need to preserve the
  * original external ID, store it in a separate column.
  *
- * @category String
+ * @group String
  */
 export declare const createIdFromString: <B extends string = never>(value: string) => [B] extends [never] ? Id : Id & Brand<B>;
 /**
@@ -1172,7 +1269,7 @@ export declare const createIdAsUuidv7: <B extends string = never>(deps: RandomBy
  * type TodoId = typeof TodoId.Type;
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const id: <Table extends TypeName>(table: Table) => TableId<Table>;
 export interface TableId<Table extends TypeName> extends Type<"Id", string & Brand<"Id"> & Brand<Table>, string, TableIdError<Table>, string, StringError> {
@@ -1183,7 +1280,7 @@ export interface TableIdError<Table extends TypeName = TypeName> extends TypeErr
 }
 export declare const formatTableIdError: TypeErrorFormatter<TableIdError<Capitalize<string>>>;
 /** Binary representation of an {@link Id}. */
-export declare const IdBytes: BrandType<BrandType<Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, Uint8ArrayError, Uint8Array<ArrayBufferLike>, Uint8ArrayError>, "Length16", LengthError<16>, Uint8ArrayError>, "IdBytes", BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>, never>;
+export declare const IdBytes: BrandType<BrandType<Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, Uint8ArrayError, Uint8Array<ArrayBufferLike>, Uint8ArrayError>, "Length16", LengthError<16>, Uint8ArrayError>, "IdBytes", BrandWithoutRefineError<"IdBytes", Uint8ArrayError | LengthError<16>>, never>;
 export type IdBytes = typeof IdBytes.Type;
 export declare const idBytesTypeValueLength: NonNegativeInt;
 export declare const idToIdBytes: (id: Id) => IdBytes;
@@ -1200,7 +1297,7 @@ export declare const idBytesToId: (idBytes: IdBytes) => Id;
  * const errorResult = PositiveNumber.from(-5); // err
  * ```
  *
- * @category Number
+ * @group Number
  */
 export declare const positive: BrandFactory<"Positive", number, PositiveError>;
 export interface PositiveError extends TypeError<"Positive"> {
@@ -1215,7 +1312,7 @@ export declare const formatPositiveError: TypeErrorFormatter<PositiveError>;
  * const NegativeNumber = negative(Number);
  * ```
  *
- * @category Number
+ * @group Number
  */
 export declare const negative: BrandFactory<"Negative", number, NegativeError>;
 export interface NegativeError extends TypeError<"Negative"> {
@@ -1230,7 +1327,7 @@ export declare const formatNegativeError: TypeErrorFormatter<NegativeError>;
  * const NonPositiveNumber = nonPositive(Number);
  * ```
  *
- * @category Number
+ * @group Number
  */
 export declare const nonPositive: BrandFactory<"NonPositive", number, NonPositiveError>;
 export interface NonPositiveError extends TypeError<"NonPositive"> {
@@ -1245,7 +1342,7 @@ export declare const formatNonPositiveError: TypeErrorFormatter<NonPositiveError
  * const NonNegativeNumber = nonNegative(Number);
  * ```
  *
- * @category Number
+ * @group Number
  */
 export declare const nonNegative: BrandFactory<"NonNegative", number, NonNegativeError>;
 export interface NonNegativeError extends TypeError<"NonNegative"> {
@@ -1254,87 +1351,81 @@ export declare const formatNonNegativeError: TypeErrorFormatter<NonNegativeError
 /**
  * Non-negative number (≥ 0).
  *
- * @category Number
+ * @group Number
  */
 export declare const NonNegativeNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonNegative", NonNegativeError, NumberError>;
 export type NonNegativeNumber = typeof NonNegativeNumber.Type;
 /**
  * Positive number (> 0).
  *
- * @category Number
+ * @group Number
  */
-export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NonNegativeError | NumberError>;
+export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NumberError | NonNegativeError>;
 export type PositiveNumber = typeof PositiveNumber.Type;
 /**
  * Non-positive number (≤ 0).
  *
- * @category Number
+ * @group Number
  */
 export declare const NonPositiveNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonPositive", NonPositiveError, NumberError>;
 export type NonPositiveNumber = typeof NonPositiveNumber.Type;
 /**
  * Negative number (< 0).
  *
- * @category Number
+ * @group Number
  */
 export declare const NegativeNumber: BrandType<Type<"Brand", number & Brand<"NonPositive">, number, NonPositiveError, number, NumberError>, "Negative", NegativeError, NumberError | NonPositiveError>;
 export type NegativeNumber = typeof NegativeNumber.Type;
-/**
- * Integer within the safe range of JavaScript numbers.
- *
- * ### Example
- *
- * ```ts
- * const Int = int(Number);
- * ```
- *
- * @category Number
- */
-export declare const int: BrandFactory<"Int", number, IntError>;
 export interface IntError extends TypeError<"Int"> {
 }
 export declare const formatIntError: TypeErrorFormatter<IntError>;
 /**
  * Integer within the safe range of JavaScript numbers.
  *
- * @category Number
+ * @group Number
  */
 export declare const Int: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Int", IntError, NumberError>;
 export type Int = typeof Int.Type;
 /**
  * Non-negative integer (≥ 0).
  *
- * @category Number
+ * @group Number
  */
-export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, IntError | NumberError>;
+export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, NumberError | IntError>;
 export type NonNegativeInt = typeof NonNegativeInt.Type;
+/** Minimum {@link NonNegativeInt} value (0). */
+export declare const zeroNonNegativeInt: number & Brand<"Int"> & Brand<"NonNegative">;
 /**
  * Positive integer (> 0).
  *
- * @category Number
+ * @group Number
  */
-export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, IntError | NumberError>, "Positive", PositiveError, NonNegativeError | IntError | NumberError>;
+export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, NumberError | IntError>, "Positive", PositiveError, NumberError | NonNegativeError | IntError>;
 export type PositiveInt = typeof PositiveInt.Type;
-/** Maximum safe positive integer value for practically infinite operations. */
+/** {@link PositiveInt} value 1. */
+export declare const onePositiveInt: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">;
+/** Maximum {@link PositiveInt} value (MAX_SAFE_INTEGER). */
 export declare const maxPositiveInt: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">;
 /**
  * Non-positive integer (≤ 0).
  *
- * @category Number
+ * @group Number
  */
-export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, IntError | NumberError>;
+export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, NumberError | IntError>;
 export type NonPositiveInt = typeof NonPositiveInt.Type;
 /**
  * Negative integer (< 0).
  *
- * @category Number
+ * @group Number
  */
-export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, IntError | NumberError>, "Negative", NegativeError, IntError | NumberError | NonPositiveError>;
+export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, NumberError | IntError>, "Negative", NegativeError, NumberError | IntError | NonPositiveError>;
 export type NegativeInt = typeof NegativeInt.Type;
 /**
  * Number greater than a specified value.
  *
- * @category Number
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
+ * @group Number
  */
 export declare const greaterThan: <Min extends number>(min: Min) => BrandFactory<`GreaterThan${Min}`, number, GreaterThanError<Min>>;
 export interface GreaterThanError<Min extends number = number> extends TypeError<"GreaterThan"> {
@@ -1344,7 +1435,9 @@ export declare const formatGreaterThanError: TypeErrorFormatter<GreaterThanError
 /**
  * Number less than a specified value.
  *
- * @category Number
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
+ * @group Number
  */
 export declare const lessThan: <Max extends number>(max: Max) => BrandFactory<`LessThan${Max}`, number, LessThanError<Max>>;
 export interface LessThanError<Max extends number = number> extends TypeError<"LessThan"> {
@@ -1354,7 +1447,9 @@ export declare const formatLessThanError: TypeErrorFormatter<LessThanError<numbe
 /**
  * Number ≥ a specified value.
  *
- * @category Number
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
+ * @group Number
  */
 export declare const greaterThanOrEqualTo: <Min extends number>(min: Min) => BrandFactory<`GreaterThanOrEqualTo${Min}`, number, GreaterThanOrEqualToError<Min>>;
 export interface GreaterThanOrEqualToError<Min extends number = number> extends TypeError<"GreaterThanOrEqualTo"> {
@@ -1364,7 +1459,9 @@ export declare const formatGreaterThanOrEqualToError: TypeErrorFormatter<Greater
 /**
  * Number ≤ a specified value.
  *
- * @category Number
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
+ * @group Number
  */
 export declare const lessThanOrEqualTo: <Max extends number>(max: Max) => BrandFactory<`LessThanOrEqualTo${Max}`, number, LessThanOrEqualToError<Max>>;
 export interface LessThanOrEqualToError<Max extends number = number> extends TypeError<"LessThanOrEqualTo"> {
@@ -1374,19 +1471,19 @@ export declare const formatLessThanOrEqualToError: TypeErrorFormatter<LessThanOr
 /**
  * Number that is not NaN.
  *
- * @category Number
+ * @group Number
  */
 export declare const nonNaN: BrandFactory<"NonNaN", number, NonNaNError>;
 export interface NonNaNError extends TypeError<"NonNaN"> {
 }
 export declare const formatNonNaNError: TypeErrorFormatter<NonNaNError>;
-/** @category Number */
+/** @group Number */
 export declare const NonNaNNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonNaN", NonNaNError, NumberError>;
 export type NonNaNNumber = typeof NonNaNNumber.Type;
 /**
  * Finite number.
  *
- * @category Number
+ * @group Number
  */
 export declare const finite: BrandFactory<"Finite", number, FiniteError>;
 export interface FiniteError extends TypeError<"Finite"> {
@@ -1403,14 +1500,16 @@ export declare const formatFiniteError: TypeErrorFormatter<FiniteError>;
  * finite (e.g., `Infinity`, `-Infinity`, or `NaN`). Using `FiniteNumber` helps
  * prevent these unexpected behaviors when working with JSON serialization.
  *
- * @category Number
+ * @group Number
  */
 export declare const FiniteNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>;
 export type FiniteNumber = typeof FiniteNumber.Type;
 /**
  * Number that is a multiple of a divisor.
  *
- * @category Number
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
+ * @group Number
  */
 export declare const multipleOf: <Divisor extends number>(divisor: Divisor) => BrandFactory<`MultipleOf${Divisor}`, number, MultipleOfError<Divisor>>;
 export interface MultipleOfError<Divisor extends number = number> extends TypeError<"MultipleOf"> {
@@ -1420,6 +1519,8 @@ export declare const formatMultipleOfError: TypeErrorFormatter<MultipleOfError<n
 /**
  * Number within a range, inclusive.
  *
+ * Use numeric literal, not expression. See {@link BrandFactory}.
+ *
  * ### Example
  *
  * ```ts
@@ -1428,7 +1529,7 @@ export declare const formatMultipleOfError: TypeErrorFormatter<MultipleOfError<n
  * const errorResult = Between1And10.from(11); // err
  * ```
  *
- * @category Number
+ * @group Number
  */
 export declare const between: <Min extends number, Max extends number>(min: Min, max: Max) => BrandFactory<`Between${Min}-${Max}`, number, BetweenError<Min, Max>>;
 export interface BetweenError<Min extends number = number, Max extends number = number> extends TypeError<"Between"> {
@@ -1451,7 +1552,7 @@ export declare const formatBetweenError: TypeErrorFormatter<BetweenError<number,
  *
  * TODO: Add JsonValue
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const literal: <T extends Literal>(expected: T) => LiteralType<T>;
 export interface LiteralType<T extends Literal> extends Type<"Literal", T, WidenLiteral<T>, LiteralError<T>> {
@@ -1464,7 +1565,7 @@ export declare const formatLiteralError: TypeErrorFormatter<LiteralError<Literal
 /**
  * Array of a specific {@link Type}.
  *
- * Usage:
+ * ### Example
  *
  * ```ts
  * const NumberArray = array(Number);
@@ -1473,8 +1574,8 @@ export declare const formatLiteralError: TypeErrorFormatter<LiteralError<Literal
  * const result2 = NumberArray.from(["a", "b"]); // err(...)
  * ```
  *
- * @category Base Factories
- * @category Array
+ * @group Base factories
+ * @group Array
  */
 export declare const array: <ElementType extends AnyType>(element: ElementType) => ArrayType<ElementType>;
 /** ArrayType extends Type with an additional `element` property for reflection. */
@@ -1502,7 +1603,7 @@ export declare const formatArrayError: <Error extends TypeError>(formatTypeError
  * const result2 = NumberSet.from(new Set(["a", "b"])); // err(...)
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const set: <ElementType extends AnyType>(element: ElementType) => SetType<ElementType>;
 /** SetType extends Type with an additional `element` property for reflection. */
@@ -1542,8 +1643,8 @@ export declare const formatSetError: <Error extends TypeError>(formatTypeError:
  * StringToNumberRecord.from({ a: "x", b: 2 });
  * ```
  *
- * @category Base Factories
- * @category Object
+ * @group Base factories
+ * @group Object
  */
 export declare const record: <KeyName extends TypeName, KeyT extends string, KeyInput extends string, KeyError extends TypeError, KeyParent extends string, KeyParentError extends TypeError, Value extends AnyType>(keyType: Type<KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError>, valueType: Value) => RecordType<KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError, Value>;
 /**
@@ -1585,22 +1686,22 @@ export declare const formatRecordError: <Error extends TypeError>(formatTypeErro
  *
  * https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures
  *
- * ### Examples
+ * ### Example
  *
- * #### Basic Object Validation
+ * ## Basic Object Validation
  *
  * ```ts
  * const User = object({
  *   name: NonEmptyTrimmedString,
  *   age: PositiveNumber,
  * });
- * type User = typeof User.Type;
+ * interface User extends InferType<typeof User> {}
  *
  * const result = User.from({ name: "John", age: 30 }); // ok({ name: "John", age: 30 })
  * const error = User.from({ name: "John", age: -5 }); // err
  * ```
  *
- * #### Optional Properties
+ * ## Optional Properties
  *
  * In this example the `age` property is marked as optional using
  * {@link optional}.
@@ -1610,10 +1711,10 @@ export declare const formatRecordError: <Error extends TypeError>(formatTypeErro
  *   name: NonEmptyString, // Required
  *   age: optional(PositiveNumber), // Optional
  * });
- * type User = typeof User.Type;
+ * interface User extends InferType<typeof User> {}
  * ```
  *
- * #### Allowing Additional Properties
+ * ## Allowing Additional Properties
  *
  * ```ts
  * const UserWithAnyExtraProperties = object(
@@ -1632,7 +1733,7 @@ export declare const formatRecordError: <Error extends TypeError>(formatTypeErro
  * });
  * ```
  *
- * #### Combining Fixed and Flexible Properties
+ * ## Combining Fixed and Flexible Properties
  *
  * ```ts
  * const NumberDictionary = object(
@@ -1669,10 +1770,11 @@ export declare const formatRecordError: <Error extends TypeError>(formatTypeErro
  * );
  * ```
  *
- * @category Base Factories
- * @category Object
+ * @group Base factories
+ * @group Object
  */
 export declare function object<Props extends Record<string, AnyType>>(props: Props): ObjectType<Props>;
+/** With additional record properties. */
 export declare function object<Props extends Record<string, AnyType>, KeyName extends TypeName, KeyT extends string, KeyInput extends string, KeyError extends TypeError, KeyParent extends string, KeyParentError extends TypeError, Value extends AnyType>(props: Props, record: RecordType<KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError, Value>): ObjectWithRecordType<Props, KeyName, KeyT, KeyInput, KeyError, KeyParent, KeyParentError, Value>;
 /**
  * ObjectType extends {@link Type} with an additional `props` property for
@@ -1718,7 +1820,7 @@ export interface ObjectError<PropsErrors extends Record<string, TypeError> = Rec
  * Merge Error and ParentError into one ObjectError so tooltips and error
  * messages are easier to read.
  *
- * @category Utilities
+ * @group Utilities
  */
 export type MergeObjectTypeErrors<T extends ObjectType<any>> = T extends ObjectType<infer Props> ? ObjectError<{
     [K in keyof Props]: InferErrors<Props[K]>;
@@ -1752,6 +1854,170 @@ export interface ObjectWithRecordError<PropsErrors extends Record<string, TypeEr
 }> {
 }
 export declare const formatObjectWithRecordError: <Error extends TypeError>(formatTypeError: TypeErrorFormatter<Error>) => TypeErrorFormatter<ObjectWithRecordError<Record<string, Error>, Error, Error>>;
+/**
+ * Base interface for objects with a discriminant `type` property.
+ *
+ * This enables
+ * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions | discriminated unions}
+ * (also known as tagged unions) — a pattern where TypeScript uses a literal
+ * `type` field to narrow union types automatically.
+ *
+ * ## Why Discriminated Unions?
+ *
+ * Discriminated unions model states that are **mutually exclusive**. Instead of
+ * optional fields and boolean flags that can combine into invalid
+ * configurations, each variant is a distinct type. This makes illegal states
+ * unrepresentable — invalid combinations cannot exist, so bugs cannot create
+ * them.
+ *
+ * Benefits:
+ *
+ * - **Self-documenting** — Union cases immediately show all possible states
+ * - **Compile-time safety** — TypeScript enforces handling all cases
+ * - **Refactoring-friendly** — Adding a new state breaks code that doesn't handle
+ *   it
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Bad: optional fields allow invalid states (no contact info at all)
+ * interface Contact {
+ *   readonly email?: Email;
+ *   readonly phone?: Phone;
+ * }
+ *
+ * // Good: discriminated union makes "at least one" explicit
+ * interface EmailOnly extends Typed<"EmailOnly"> {
+ *   readonly email: Email;
+ * }
+ * interface PhoneOnly extends Typed<"PhoneOnly"> {
+ *   readonly phone: Phone;
+ * }
+ * interface EmailAndPhone extends Typed<"EmailAndPhone"> {
+ *   readonly email: Email;
+ *   readonly phone: Phone;
+ * }
+ *
+ * type ContactInfo = EmailOnly | PhoneOnly | EmailAndPhone;
+ * ```
+ *
+ * ```ts
+ * interface Pending extends Typed<"Pending"> {
+ *   readonly createdAt: DateIso;
+ * }
+ * interface Shipped extends Typed<"Shipped"> {
+ *   readonly trackingNumber: TrackingNumber;
+ * }
+ * interface Delivered extends Typed<"Delivered"> {
+ *   readonly deliveredAt: DateIso;
+ * }
+ * interface Cancelled extends Typed<"Cancelled"> {
+ *   readonly reason: CancellationReason;
+ * }
+ *
+ * type OrderState = Pending | Shipped | Delivered | Cancelled;
+ *
+ * // TypeScript enforces exhaustiveness via return type
+ * const getStatusMessage = (state: OrderState): string => {
+ *   switch (state.type) {
+ *     case "Pending":
+ *       return "Order placed";
+ *     case "Shipped":
+ *       return `Shipped: ${state.trackingNumber}`;
+ *     case "Delivered":
+ *       return `Delivered on ${state.deliveredAt.toLocaleDateString()}`;
+ *     case "Cancelled":
+ *       return `Cancelled: ${state.reason}`;
+ *   }
+ * };
+ *
+ * // For void functions, use exhaustiveCheck to ensure all cases are handled
+ * const logState = (state: OrderState): void => {
+ *   switch (state.type) {
+ *     case "Pending":
+ *       console.log("Order placed");
+ *       break;
+ *     case "Shipped":
+ *       console.log(`Shipped: ${state.trackingNumber}`);
+ *       break;
+ *     case "Delivered":
+ *       console.log(
+ *         `Delivered on ${state.deliveredAt.toLocaleDateString()}`,
+ *       );
+ *       break;
+ *     case "Cancelled":
+ *       console.log(`Cancelled: ${state.reason}`);
+ *       break;
+ *     default:
+ *       exhaustiveCheck(state);
+ *   }
+ * };
+ * ```
+ *
+ * ## Why `type` (and not e.g. `_tag`)?
+ *
+ * Underscore-prefixing is meant to avoid clashing with domain properties, but
+ * proper discriminated union design means the discriminant IS the domain
+ * concept — there's no clash to avoid. The `type` prop name also aligns with
+ * {@link Type}'s name. If an entity has a meaningful "type" (like product
+ * category), model it as the discriminant itself:
+ *
+ * ```ts
+ * interface Electronics extends Typed<"Electronics"> {
+ *   voltage: Voltage;
+ * }
+ * interface Clothing extends Typed<"Clothing"> {
+ *   size: Size;
+ * }
+ * type Product = Electronics | Clothing;
+ * ```
+ *
+ * @see {@link exhaustiveCheck} to ensure all cases are handled in void functions.
+ * @see {@link typed} for runtime-validated typed objects.
+ */
+export interface Typed<T extends TypeName> {
+    readonly type: T;
+}
+/**
+ * Creates a runtime-validated typed object with a `type` discriminant.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Card = typed("Card", {
+ *   cardNumber: CardNumber,
+ *   expiry: DateIso,
+ * });
+ *
+ * const Cash = typed("Cash", {
+ *   currency: NonEmptyTrimmedString,
+ * });
+ *
+ * const Payment = union(Card, Cash);
+ * type Payment = typeof Payment.Type;
+ *
+ * const result = Payment.fromUnknown(data);
+ * if (result.ok) {
+ *   switch (result.value.type) {
+ *     case "Card":
+ *       console.log(result.value.cardNumber);
+ *       break;
+ *     case "Cash":
+ *       console.log(result.value.currency);
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Typed} for type-only discrimination.
+ */
+export declare function typed<Tag extends TypeName>(tag: Tag): TypedType<Tag>;
+/** With additional properties. */
+export declare function typed<Tag extends TypeName, Props extends Record<string, AnyType>>(tag: Tag, props: Props): TypedType<Tag, Props>;
+/** Return type of {@link typed}. */
+export type TypedType<Tag extends TypeName, Props extends Record<string, AnyType> = Record<never, never>> = ObjectType<{
+    type: LiteralType<Tag>;
+} & Props>;
 /**
  * Union {@link Type}.
  *
@@ -1774,9 +2040,10 @@ export declare const formatObjectWithRecordError: <Error extends TypeError>(form
  * const result3 = StringOrNumber.from(42); // ok(42)
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare function union<Members extends [AnyType, AnyType, ...ReadonlyArray<AnyType>]>(...members: Members): UnionType<Members>;
+/** With literal values. */
 export declare function union<Literals extends [Literal, Literal, ...ReadonlyArray<Literal>]>(...literals: Literals): UnionType<{
     [K in keyof Literals]: LiteralType<Literals[K]>;
 }>;
@@ -1792,6 +2059,99 @@ export interface UnionError<E extends TypeError = TypeError> extends TypeError<"
 }
 export declare const formatUnionError: <Error extends TypeError>(formatTypeError: TypeErrorFormatter<Error>) => TypeErrorFormatter<UnionError<Error>>;
 export declare const isUnionType: (t: AnyType) => t is UnionType<[AnyType, ...ReadonlyArray<AnyType>]>;
+/**
+ * Creates a {@link Type} for {@link Result} values.
+ *
+ * Use for validating serialized Results from storage, APIs, or message passing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const SyncResponse = result(
+ *   object({ timestamp: NonNegativeInt }),
+ *   typed("SyncError", { message: String }),
+ * );
+ *
+ * // Validate response from worker or API
+ * const validated = SyncResponse.from(JSON.parse(message));
+ * if (!validated.ok) return validated; // validation error
+ * // validated.value is Result<{ timestamp }, SyncError>
+ * ```
+ *
+ * @group Composite factories
+ */
+export declare const result: <OkType extends AnyType, ErrType extends AnyType>(okType: OkType, errType: ErrType) => UnionType<[ObjectType<{
+    ok: LiteralType<true>;
+    value: OkType;
+}>, ObjectType<{
+    ok: LiteralType<false>;
+    error: ErrType;
+}>]>;
+/**
+ * A {@link result} type for `Result<unknown, unknown>`.
+ *
+ * Useful for serializing Results where the value and error types are unknown.
+ *
+ * @group Composite factories
+ */
+export declare const UnknownResult: UnionType<[ObjectType<{
+    ok: LiteralType<true>;
+    value: Type<"Unknown", unknown, unknown, never, unknown, never>;
+}>, ObjectType<{
+    ok: LiteralType<false>;
+    error: Type<"Unknown", unknown, unknown, never, unknown, never>;
+}>]>;
+export type UnknownResult = typeof UnknownResult.Type;
+/**
+ * Creates a {@link Type} for {@link NextResult} with three outcomes.
+ *
+ * Validates results where the producer responds with:
+ *
+ * - `Ok<A>` — produced a value
+ * - `Err<Done<D>>` — completed normally with a done value
+ * - `Err<E>` — failed with an error
+ *
+ * ### Example
+ *
+ * ```ts
+ * const MyNextResult = nextResult(Item, MyError, Summary);
+ *
+ * const validated = MyNextResult.fromUnknown(data);
+ * if (!validated.ok) return validated;
+ *
+ * const result = validated.value;
+ * if (result.ok) {
+ *   console.log(result.value);
+ * } else if (result.error.type === "Done") {
+ *   console.log("Done:", result.error.done);
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ *
+ * @group Composite factories
+ */
+export declare const nextResult: <ValueType extends AnyType, ErrorType extends AnyType, DoneType extends AnyType>(valueType: ValueType, errorType: ErrorType, doneType: DoneType) => ReturnType<typeof result<ValueType, UnionType<[ErrorType, TypedType<"Done", {
+    done: DoneType;
+}>]>>>;
+/**
+ * A {@link nextResult} type for `NextResult<unknown, unknown, unknown>`.
+ *
+ * Useful for checking if a value is a {@link NextResult} via
+ * `UnknownNextResult.is(value)`.
+ *
+ * @group Composite factories
+ */
+export declare const UnknownNextResult: UnionType<[ObjectType<{
+    ok: LiteralType<true>;
+    value: Type<"Unknown", unknown, unknown, never, unknown, never>;
+}>, ObjectType<{
+    ok: LiteralType<false>;
+    error: UnionType<[Type<"Unknown", unknown, unknown, never, unknown, never>, TypedType<"Done", {
+        done: Type<"Unknown", unknown, unknown, never, unknown, never>;
+    }>]>;
+}>]>;
+export type UnknownNextResult = typeof UnknownNextResult.Type;
 /**
  * Recursive {@link Type}.
  *
@@ -1825,7 +2185,7 @@ export declare const isUnionType: (t: AnyType) => t is UnionType<[AnyType, ...Re
  * );
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const recursive: <ParentType extends AnyType>(create: () => ParentType) => RecursiveType<ParentType>;
 export interface RecursiveType<ParentType extends AnyType> extends Type<"Recursive", InferType<ParentType>, InferInput<ParentType>, InferError<ParentType>, InferParent<ParentType>, InferParentError<ParentType>> {
@@ -1843,7 +2203,7 @@ export interface RecursiveType<ParentType extends AnyType> extends Type<"Recursi
  * NullOrString.from(42); // err(...)
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const nullOr: <T extends AnyType>(type: T) => UnionType<[typeof Null, T]>;
 /**
@@ -1858,7 +2218,7 @@ export declare const nullOr: <T extends AnyType>(type: T) => UnionType<[typeof N
  * UndefinedOrString.from(42); // err(...)
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const undefinedOr: <T extends AnyType>(type: T) => UnionType<[typeof Undefined, T]>;
 /**
@@ -1877,7 +2237,7 @@ export declare const undefinedOr: <T extends AnyType>(type: T) => UnionType<[typ
  * NullishOrString.from(42); // err(...)
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const nullishOr: <T extends AnyType>(type: T) => UnionType<[typeof Undefined, typeof Null, T]>;
 /**
@@ -1894,7 +2254,7 @@ export declare const nullishOr: <T extends AnyType>(type: T) => UnionType<[typeo
  * const error = NameAndAge.from(["Alice", -10]); // err
  * ```
  *
- * @category Base Factories
+ * @group Base factories
  */
 export declare const tuple: <Elements extends [AnyType, ...ReadonlyArray<AnyType>]>(...elements: Elements) => TupleType<Elements>;
 /**
@@ -1939,7 +2299,7 @@ export declare const formatTupleError: <Error extends TypeError>(formatTypeError
  *
  * https://www.sqlite.org/c3ref/int64.html
  *
- * @category Number
+ * @group Number
  */
 export declare const Int64: BrandType<Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>, "Int64", Int64Error, BigIntError>;
 export type Int64 = typeof Int64.Type;
@@ -1949,14 +2309,37 @@ export declare const formatInt64Error: TypeErrorFormatter<Int64Error>;
 /**
  * Stringified {@link Int64}.
  *
- * @category String
+ * @group String
  */
 export declare const Int64String: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, "Int64", Int64StringError, StringError | TrimmedError | MinLengthError<1>>;
 export type Int64String = typeof Int64String.Type;
 export interface Int64StringError extends TypeError<"Int64String"> {
 }
 export declare const formatInt64StringError: TypeErrorFormatter<Int64StringError>;
+/**
+ * Validated JSON-compatible value.
+ *
+ * This is the output side of JSON data in Evolu. It uses {@link FiniteNumber}
+ * instead of `number` because JSON numbers are expected to be finite once the
+ * value has been parsed or validated.
+ *
+ * Compare with {@link JsonValueInput}, which represents caller-provided input
+ * before validation.
+ */
 export type JsonValue = string | FiniteNumber | boolean | null | JsonArray | JsonObject;
+/**
+ * JSON-compatible input value before validation.
+ *
+ * This is broader than {@link JsonValue} because inputs arrive as ordinary
+ * JavaScript values, so numbers are typed as `number` before validation can
+ * narrow them to {@link FiniteNumber}.
+ *
+ * That means `JsonValueInput` can temporarily contain numbers that are lossy in
+ * JSON serialization. For example, `JSON.stringify(NaN)` and
+ * `JSON.stringify(Infinity)` produce `null`, and `JSON.stringify(-0)` produces
+ * `0`. Use {@link JsonValue} when the value must already satisfy JSON numeric
+ * constraints.
+ */
 export type JsonValueInput = string | number | boolean | null | JsonArrayInput | JsonObjectInput;
 export type JsonValueError = UnionError<StringError | BooleanError | NullError | FiniteError | NumberError | ArrayError<JsonValueError> | RecordError<StringError, JsonValueError>>;
 export interface JsonObject {
@@ -1971,19 +2354,19 @@ export type JsonArrayInput = ReadonlyArray<JsonValueInput>;
  * JSON-compatible value: string, {@link FiniteNumber}, boolean, null,
  * {@link JsonArray}, or {@link JsonObject}.
  *
- * @category Base Types
+ * @group Base Types
  */
 export declare const JsonValue: RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>;
 /**
  * JSON-compatible array of {@link JsonValue} elements.
  *
- * @category Array
+ * @group Array
  */
 export declare const JsonArray: ArrayType<RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>>;
 /**
  * JSON-compatible object with string keys and {@link JsonValue} values.
  *
- * @category Object
+ * @group Object
  */
 export declare const JsonObject: RecordType<"String", string, string, StringError, string, StringError, RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>>;
 export declare const parseJson: (value: string) => Result<JsonValue, JsonError>;
@@ -1997,7 +2380,7 @@ export declare const parseJson: (value: string) => Result<JsonValue, JsonError>;
  * const error = Json.from("invalid json"); // err
  * ```
  *
- * @category String
+ * @group String
  */
 export declare const Json: BrandType<Type<"String", string, string, StringError, string, StringError>, "Json", JsonError, StringError>;
 export type Json = typeof Json.Type;
@@ -2027,7 +2410,7 @@ export declare const jsonToJsonValue: (value: Json) => JsonValue;
  *   name: NonEmptyString100,
  *   age: FiniteNumber,
  * });
- * type Person = typeof Person.Type;
+ * interface Person extends InferType<typeof Person> {}
  *
  * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
  *   Person,
@@ -2095,7 +2478,7 @@ export declare const isOptionalType: (x: unknown) => x is OptionalType<any>;
  * PartialUser.from({ age: -5 });
  * ```
  *
- * @category Object
+ * @group Object
  */
 export declare const partial: <Props extends Record<string, AnyType>>(props: Props) => ObjectType<{ [K in keyof Props]: OptionalType<Props[K]>; }>;
 /**
@@ -2104,7 +2487,7 @@ export declare const partial: <Props extends Record<string, AnyType>>(props: Pro
  * entirely, or set it to `null`, or set it to the non-null member of the
  * union.
  *
- * @category Object
+ * @group Object
  */
 export declare const nullableToOptional: <Props extends Record<string, AnyType>>(props: Props) => ObjectType<NullableToOptionalProps<Props>>;
 export type NullableToOptionalProps<Props extends Record<string, AnyType>> = {
@@ -2116,21 +2499,9 @@ export type NullTypeInMembers<Members extends [AnyType, ...Array<AnyType>]> = Me
 /**
  * Create a new `object` {@link Type} by omitting some keys.
  *
- * @category Object
+ * @group Object
  */
-export declare function omit<T extends ObjectType<any>, Keys extends keyof T["props"]>(objectType: T, ...keys: ReadonlyArray<Keys>): ObjectType<Omit<T["props"], Keys>>;
-export declare const maxMutationSize = 655360;
-/**
- * Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use
- * the `maxProtocolMessageRangesSize`. The max size is 640KB in bytes, measured
- * via MessagePack. Evolu Protocol DbChange will be smaller thanks to various
- * optimizations.
- */
-export declare const validMutationSize: <T extends AnyType>(type: T) => BrandType<T, "ValidMutationSize", ValidMutationSizeError, InferErrors<T>>;
-export interface ValidMutationSizeError extends TypeError<"ValidMutationSize"> {
-}
-export declare const formatValidMutationSizeError: TypeErrorFormatter<ValidMutationSizeError>;
-export type ValidMutationSize<Props extends Record<string, AnyType>> = BrandType<ObjectType<Props>, "ValidMutationSize", ValidMutationSizeError, InferErrors<ObjectType<Props>>>;
+export declare const omit: <T extends ObjectType<any>, Keys extends keyof T["props"]>(objectType: T, ...keys: ReadonlyArray<Keys>) => ObjectType<Omit<T["props"], Keys>>;
 /**
  * Union of all `TypeError`s defined in the `Type.ts` file, including base type
  * errors (e.g., `StringError`, `NumberError`), composite type errors
@@ -2142,9 +2513,9 @@ export type ValidMutationSize<Props extends Record<string, AnyType>> = BrandType
  * Used by {@link createFormatTypeError} to generate human-readable error
  * messages.
  *
- * @category Utilities
+ * @group Utilities
  */
-export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | SimplePasswordError | IdError | TableIdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | Int64StringError | JsonError | ValidMutationSizeError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | SetError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | TupleError<TypeErrors<ExtraErrors>>;
+export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | SimplePasswordError | IdError | TableIdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | Int64StringError | JsonError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | SetError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | TupleError<TypeErrors<ExtraErrors>>;
 /**
  * Formats Evolu Type errors into user-friendly messages.
  *
@@ -2223,18 +2594,20 @@ export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | Nu
  * };
  * ```
  *
- * @category Utilities
+ * @group Utilities
  */
 export declare const createFormatTypeError: <ExtraErrors extends TypeError = never>(extraFormatter?: TypeErrorFormatter<ExtraErrors>) => TypeErrorFormatter<TypeErrors<ExtraErrors>>;
 /**
  * Converts an Evolu {@link TypeError} to Standard Schema V1 issues format.
  *
  * This function recursively converts Evolu's typed errors into the Standard
- * Schema issue format with proper path tracking for nested structures.
+ * Schema issue format with proper path tracking for nested structures. The
+ * `message` field contains the JSON-serialized typed error, which users can
+ * deserialize and format using appropriate {@link TypeErrorFormatter}s.
  *
- * @category Utilities
+ * @group Utilities
  */
-export declare const typeErrorToStandardSchemaIssues: <ExtraErrors extends TypeError = never>(error: TypeErrors<ExtraErrors>, formatTypeError: TypeErrorFormatter<TypeErrors<ExtraErrors>>, path?: ReadonlyArray<PropertyKey>) => ReadonlyArray<StandardSchemaV1.Issue>;
+export declare const typeErrorToStandardSchemaIssues: <ExtraErrors extends TypeError = never>(error: TypeErrors<ExtraErrors>, path?: ReadonlyArray<PropertyKey>) => ReadonlyArray<StandardSchemaV1.Issue>;
 /** The Standard Schema interface. */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
     /** The Standard Schema properties. */