@vicin/phantom 1.0.2 → 1.0.5

package/dist/index.d.mts

@@ -0,0 +1,1353 @@
+declare namespace assertors {
+    /**
+     * Creates a typed caster that assigns a {@link Brand} to a value.
+     *
+     * This is a zero-cost runtime assertion helper — it simply returns the value
+     * with the brand's nominal type applied. Use it for simple branded primitives
+     * where you know the value is valid.
+     *
+     * @template B - The brand declaration to assign.
+     * @returns A function that casts any value to the branded type.
+     */
+    const asBrand: <B extends Brand.Any>() => <T>(value: T) => Brand.Assign<B, T>;
+    /**
+     * Creates a typed caster that assigns an {@link Identity} to a value.
+     *
+     * This is a zero-cost runtime assertion helper — it simply returns the value
+     * with the identity's nominal type applied. Use it when you know a value
+     * conforms to an identity but need to assert it for the type system.
+     *
+     * @template I - The identity declaration to assign.
+     * @returns A function that casts any value to the assigned identity type.
+     */
+    const asIdentity: <I extends Identity.Any>() => </**
+     * Creates a typed caster that assigns a {@link Brand} to a value.
+     *
+     * This is a zero-cost runtime assertion helper — it simply returns the value
+     * with the brand's nominal type applied. Use it for simple branded primitives
+     * where you know the value is valid.
+     *
+     * @template B - The brand declaration to assign.
+     * @returns A function that casts any value to the branded type.
+     */ V>(value: V) => Identity.Assign<I, V>;
+    /**
+     * Creates a typed caster that adds a single {@link Trait} to a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The trait declaration to add.
+     * @returns A function that adds the trait to any value.
+     */
+    const addTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Add<Tr, V>;
+    /**
+     * Creates a typed caster that adds multiple {@link Trait}s to a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - Tuple of trait declarations to add.
+     * @returns A function that adds all traits to any value.
+     */
+    const addTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.AddMulti<Tr, V>;
+    /**
+     * Creates a typed caster that removes a single {@link Trait} from a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The trait declaration to remove.
+     * @returns A function that drops the trait from any value.
+     */
+    const dropTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Drop<Tr, V>;
+    /**
+     * Creates a typed caster that removes multiple {@link Trait}s from a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - Tuple of trait declarations to remove.
+     * @returns A function that drops all specified traits from any value.
+     */
+    const dropTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.DropMulti<Tr, V>;
+    /**
+     * Creates a typed applicator for a {@link Transformation}.
+     *
+     * Use this for "forward" operations (e.g., encrypt, encode, wrap).
+     * The `input` parameter is only used for type inference — it is not used at runtime.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The transformation declaration.
+     * @returns A function that applies the transformation while preserving the input type for later revert.
+     */
+    const applyTransformation: <Tr extends Transformation.Any>() => <I, T>(input: I, transformed: T) => Transformation.Apply<Tr, I, T>;
+    /**
+     * Creates a typed reverter for a {@link Transformation}.
+     *
+     * Use this for "reverse" operations (e.g., decrypt, decode, unwrap).
+     * The `transformed` parameter is used for type inference of the expected input,
+     * and `input` is the computed result that must match the stored input type.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The transformation declaration.
+     * @returns A function that reverts the transformation, stripping phantom metadata.
+     */
+    const revertTransformation: <Tr extends Transformation.Any>() => <T, I>(transformed: T, input: I) => Transformation.Revert<Tr, T, I>;
+}
+
+/**
+ * Base-type metadata.
+ *
+ * Used to constrain which runtime types a brand, identity,
+ * or transformation may be applied to.
+ */
+declare namespace BaseCore {
+    /** Marker type for base constraints */
+    type Any = {
+        __Phantom: {
+            __Base?: unknown;
+        };
+    };
+    /** Declare a base type */
+    type Of<Base> = {
+        __Phantom: {
+            __Base?: Base;
+        };
+    };
+    /** Conditionally declare a base type */
+    type OfIfExists<Base> = [Base] extends [never] ? {} : Of<Base>;
+    /** Extract the base type */
+    type BaseOf<T> = T extends {
+        __Phantom: {
+            __Base?: infer Base;
+        };
+    } ? Exclude<Base, undefined> : unknown;
+    /** Check whether a base constraint exists */
+    type HasBase<T, B = unknown> = T extends {
+        __Phantom: {
+            __Base?: B;
+        };
+    } ? true : false;
+}
+
+/**
+ * Input metadata.
+ *
+ * Utilities for attaching and querying input metadata in transformations.
+ */
+declare namespace InputCore {
+    /** Marker type for input value */
+    type Any = {
+        __Phantom: {
+            __Input: unknown;
+        };
+    };
+    /** Set input */
+    type Of<Input> = {
+        __Phantom: {
+            __Input: Input;
+        };
+    };
+    /** Conditionally set input */
+    type OfIfExists<Input> = [Input] extends [never] ? {} : {
+        __Phantom: {
+            __Input: Input;
+        };
+    };
+    /** Extract the input */
+    type InputOf<T> = T extends {
+        __Phantom: {
+            __Input: infer Input;
+        };
+    } ? Input : never;
+    /** Check whether an input exists */
+    type HasInput<T, I = unknown> = T extends {
+        __Phantom: {
+            __Input: I;
+        };
+    } ? true : false;
+}
+
+/**
+ * Optional human-readable label metadata.
+ *
+ * Labels are descriptive only and do not affect identity.
+ */
+declare namespace LabelCore {
+    /** Marker type for labeled values */
+    type Any = {
+        __Phantom: {
+            __Label?: string;
+        };
+    };
+    /** Attach a label */
+    type Of<Label extends string> = {
+        __Phantom: {
+            __Label?: Label;
+        };
+    };
+    /** Conditionally attach a label */
+    type OfIfExists<Label extends string> = [Label] extends [never] ? {} : Of<Label>;
+    /** Extract the label */
+    type LabelOf<T> = T extends {
+        __Phantom: {
+            __Label?: infer Label;
+        };
+    } ? Exclude<Label, undefined> : never;
+    /** Check whether a label exists */
+    type HasLabel<T, L extends string = string> = T extends {
+        __Phantom: {
+            __Label?: L;
+        };
+    } ? true : false;
+}
+
+/**
+ * Nominal tag metadata.
+ *
+ * Tags uniquely identify a branded or identified type.
+ * A value may only have a single tag.
+ */
+declare namespace TagCore {
+    /** Marker type for any tagged value */
+    type Any = {
+        __Phantom: {
+            __Tag: string | symbol;
+        };
+    };
+    /** Attach a specific tag */
+    type Of<Tag extends string | symbol> = {
+        __Phantom: {
+            __Tag: Tag;
+        };
+    };
+    /** Conditionally attach a tag if it exists */
+    type OfIfExists<Tag extends string | symbol> = [Tag] extends [never] ? {} : Of<Tag>;
+    /** Extract the tag from a type */
+    type TagOf<T> = T extends {
+        __Phantom: {
+            __Tag: infer Tag;
+        };
+    } ? Tag : never;
+    /** Check whether a type is tagged */
+    type HasTag<T, Ta extends string | symbol = string | symbol> = T extends {
+        __Phantom: {
+            __Tag: Ta;
+        };
+    } ? true : false;
+}
+
+/**
+ * Trait metadata.
+ *
+ * Traits behave like a set of capabilities that can be
+ * added or removed independently.
+ */
+declare namespace TraitsCore {
+    /** Marker type for trait-bearing values */
+    type Any = {
+        __Phantom: {
+            __Traits: {};
+        };
+    };
+    /** Declare a single trait */
+    type Of<Trait extends string | symbol> = {
+        __Phantom: {
+            __Traits: {
+                [K in Trait]: true;
+            };
+        };
+    };
+    /** Construct traits from an explicit trait map */
+    type FromMap<Traits extends Record<string | symbol, true>> = {
+        __Phantom: {
+            __Traits: Traits;
+        };
+    };
+    /** Conditionally declare a trait */
+    type OfIfExists<Trait extends string | symbol> = [Trait] extends [
+        never
+    ] ? {} : Of<Trait>;
+    /** Extract the trait map */
+    type TraitsOf<T> = T extends {
+        __Phantom: {
+            __Traits: infer Traits;
+        };
+    } ? Traits extends Record<string | symbol, true> ? Traits : never : never;
+    /** Extract trait keys */
+    type TraitKeysOf<T> = T extends {
+        __Phantom: {
+            __Traits: infer Traits;
+        };
+    } ? keyof Traits : never;
+    /** Check if any traits exist */
+    type HasTraits<T, Tr extends string | symbol = string | symbol> = T extends {
+        __Phantom: {
+            __Traits: Record<Tr, true>;
+        };
+    } ? true : false;
+}
+
+/**
+ * Variant metadata.
+ *
+ * Variants represent mutually exclusive states of a type.
+ */
+declare namespace VariantsCore {
+    /** Marker type for variant-bearing values */
+    type Any = {
+        __Phantom: {
+            __Variants: string;
+        };
+    };
+    /** Declare allowed variants */
+    type Of<Variants extends string> = {
+        __Phantom: {
+            __Variants: Variants;
+        };
+    };
+    /** Conditionally declare variants */
+    type OfIfExists<Variants extends string> = [Variants] extends [never] ? {} : Of<Variants>;
+    /** Extract variant union */
+    type VariantsOf<T> = T extends {
+        __Phantom: {
+            __Variants: infer Variants;
+        };
+    } ? Variants extends string ? Variants : never : never;
+    /** Check whether variants exist */
+    type HasVariants<T> = T extends {
+        __Phantom: {
+            __Variants: string;
+        };
+    } ? true : false;
+}
+
+/**
+ * Phantom meatadata object manipulators.
+ *
+ * Phantom matadata object holds all metadata used by 'phantom'.
+ */
+declare namespace PhantomCore {
+    /** Get phantom metadata object from a type */
+    type PhantomOf<T> = T extends {
+        __Phantom: infer Phantom extends object;
+    } ? Phantom : never;
+    /** Stip phantom metadata object from a type */
+    type StripPhantom<T> = T extends {
+        __Phantom: {
+            __OriginalType?: infer O;
+        };
+    } ? Exclude<O, undefined> : T;
+    /** run-time helper for 'StringPhantom', used for debugging mainly */
+    const stripPhantom: <T>(value: T) => StripPhantom<T>;
+}
+
+/** Interface of 'Brand' and 'Identity' errors. */
+interface Errors<I, T> {
+    alreadyBranded: {
+        code: 'ALREADY_BRANDED';
+        message: 'Type already branded';
+        context: {
+            type: T;
+        };
+    };
+    typeNotExtendBase: {
+        code: 'TYPE_NOT_EXTEND_BASE';
+        message: 'Type not extend base';
+        context: {
+            type: PhantomCore.StripPhantom<T>;
+            base: BaseCore.BaseOf<I>;
+        };
+    };
+    transformationMismatch: {
+        code: 'TRANSFORMATION_MISMATCH';
+        message: 'Transformation mismatch';
+        context: {
+            type: T;
+            transformation: I;
+        };
+    };
+    notTransformed: {
+        code: 'NOT_TRANSFORMED';
+        message: 'Type is not transformed';
+        context: {
+            type: T;
+        };
+    };
+}
+declare const __ErrorType: unique symbol;
+/** Unique Error type for rules validation in phantom. */
+type ErrorType<E> = {
+    [__ErrorType]: E;
+};
+
+/** --------------------------------------
+ * PhantomCore type helpers
+ * --------------------------------------- */
+/**
+ * Attach or override phantom metadata while preserving
+ * the original runtime type.
+ */
+type WithMetadata<T, Change extends object> = PhantomCore.StripPhantom<T> & {
+    __Phantom: Prettify<Merge<IfNever<PhantomCore.PhantomOf<T>>, Omit<IfNever<PhantomCore.PhantomOf<Change>>, '__Base'> & SetType<T>>>;
+};
+/**
+ * Patch phantom metadata without touching the original type.
+ * Used when mutating metadata declarations themselves.
+ */
+type PatchMetadata<T, Change extends object> = {
+    __Phantom: Prettify<Merge<IfNever<PhantomCore.PhantomOf<T>>, IfNever<PhantomCore.PhantomOf<Change>>>>;
+};
+/**
+ * Remove a metadata dimension while preserving the original type.
+ */
+type WithoutMetadata<T, S extends string> = PhantomCore.StripPhantom<T> & {
+    __Phantom: Prettify<Omit<IfNever<PhantomCore.PhantomOf<T>>, S> & SetType<T>>;
+};
+/**
+ * Update '__OriginalType' if the passed type is changed.
+ */
+type HandleOriginalType<T> = Equals<Omit<PhantomCore.StripPhantom<T>, never>, Omit<T, '__Phantom'>> extends true ? T : Omit<T, '__Phantom'> & PatchMetadata<T, {
+    __Phantom: {
+        __OriginalType?: Omit<T, '__Phantom'>;
+    };
+}>;
+/**
+ * Attaches or updates the original runtime type metadata
+ * for a nominal value.
+ *
+ * If the type already carries an `__OriginalType`, it is preserved.
+ * Otherwise, the provided type is stored as the original type.
+ *
+ * This is used to maintain a stable runtime type while layering
+ * additional phantom metadata.
+ */
+type SetType<T> = T extends {
+    __Phantom: {
+        __OriginalType?: infer O;
+    };
+} ? {
+    __OriginalType?: O;
+} : {
+    __OriginalType?: T;
+};
+/** --------------------------------------
+ * Generic helpers
+ * --------------------------------------- */
+/** Prettify type */
+type Prettify<T> = {
+    [K in keyof T]: K extends '__Phantom' | '__Traits' ? Prettify<T[K]> : T[K];
+} & {};
+/** Check equality and returns true or false */
+type Equals<A1 extends any, A2 extends any> = (<A>() => A extends A2 ? true : false) extends <A>() => A extends A1 ? true : false ? true : false;
+/** Type to replace 'never' with another type */
+type IfNever<T, R = {}> = [T] extends [never] ? R : T;
+/** Get intersection from union */
+type IntersectOf<U extends any> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Merge two objects. if matching keys between the two exists, the second object key value is used.  */
+type Merge<O1 extends object, O2 extends object> = Prettify<Omit<O1, keyof O2> & O2>;
+
+/**
+ * Branding API.
+ *
+ * Brands provide nominal typing for otherwise identical values.
+ * A value may only be branded once.
+ */
+declare namespace BrandCore {
+    /** Type guard for any brand. */
+    export type Any = TagCore.Of<string | symbol>;
+    /** Declare a brand */
+    export type Declare<T extends string | symbol, L extends string = never> = Prettify<TagCore.Of<T> & LabelCore.OfIfExists<L>>;
+    /**
+     * Assign a brand to a value.
+     * Fails if the value is already branded.
+     */
+    export type Assign<B extends Any, T> = T extends ErrorType<any> ? T : _Assign<B, HandleOriginalType<T>>;
+    /** Internal implementation of 'Brand.Assign' */
+    type _Assign<B extends Any, T> = TagCore.HasTag<T> extends true ? ErrorType<Errors<B, T>['alreadyBranded']> : WithMetadata<T, B>;
+    /**
+     * Assign a brand if possible, otherwise return the original type.
+     */
+    export type AssignSafe<B extends Any, T> = T extends ErrorType<any> ? T : _AssignSafe<B, HandleOriginalType<T>>;
+    /** Internal implementation of 'Brand.AssignSafe' */
+    type _AssignSafe<B extends Any, T> = TagCore.HasTag<T> extends true ? T : WithMetadata<T, B>;
+    /** Check whether value is branded with */
+    export type isBrand<T, B extends Any> = T extends B ? true : false;
+    export {  };
+}
+
+/**
+ * Identity API.
+ *
+ * Identities are brands with additional constraints:
+ * - Base type
+ * - Variants
+ */
+declare namespace IdentityCore {
+    /** Type guard for any identity. */
+    export type Any = TagCore.Of<string | symbol>;
+    /** Declare an identity */
+    export type Declare<T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = Prettify<TagCore.Of<T> & LabelCore.OfIfExists<L> & BaseCore.OfIfExists<B> & VariantsCore.OfIfExists<V>>;
+    /**
+     * Assign an identity to a value.
+     * Enforces base-type compatibility.
+     */
+    export type Assign<I extends Any, T> = T extends ErrorType<any> ? T : _Assign<I, HandleOriginalType<T>>;
+    /** Internal implementation of 'Identity.Assign' */
+    type _Assign<I extends Any, T> = TagCore.HasTag<T> extends true ? ErrorType<Errors<I, T>['alreadyBranded']> : T extends BaseCore.BaseOf<I> ? WithMetadata<T, I> : ErrorType<Errors<I, T>['typeNotExtendBase']>;
+    /** Safe identity assignment */
+    export type AssignSafe<I extends Any, T> = T extends ErrorType<any> ? T : _AssignSafe<I, HandleOriginalType<T>>;
+    /** Internal implementation of 'Identity.AssignSafe' */
+    type _AssignSafe<I extends Any, T> = TagCore.HasTag<T> extends true ? T : T extends BaseCore.BaseOf<I> ? WithMetadata<T, I> : ErrorType<Errors<I, T>['typeNotExtendBase']>;
+    /** Set the active variant on an identity */
+    export type WithVariant<I extends Any, V extends VariantsCore.VariantsOf<I>> = PatchMetadata<I, VariantsCore.Of<V>>;
+    /** Set the active variant on a value */
+    export type WithTypeVariant<T, V extends VariantsCore.VariantsOf<T>> = T extends ErrorType<any> ? T : _WithTypeVariant<HandleOriginalType<T>, V>;
+    /** Internal implementation of 'Identity.WithTypeVariant' */
+    type _WithTypeVariant<T, V extends VariantsCore.VariantsOf<T>> = WithMetadata<T, VariantsCore.Of<V>>;
+    /** Check whether value is branded with */
+    export type isIdentity<T, I extends Any> = T extends I ? true : false;
+    export {  };
+}
+
+/**
+ * Trait API.
+ *
+ * Traits are additive capabilities that can be attached
+ * or removed independently.
+ */
+declare namespace TraitCore {
+    /** Type guard for any trait. */
+    export type Any = TraitsCore.Of<string | symbol>;
+    /** Declare a trait */
+    export type Declare<Tr extends string | symbol> = TraitsCore.Of<Tr>;
+    /** Add a trait */
+    export type Add<Tr extends Any, T> = T extends ErrorType<any> ? T : _Add<Tr, HandleOriginalType<T>>;
+    /** Internal implementation of 'Trait.Add' */
+    type _Add<Tr extends Any, T> = WithMetadata<T, TraitsCore.FromMap<IfNever<TraitsCore.TraitsOf<T>> & IfNever<TraitsCore.TraitsOf<Tr>>>>;
+    /** Add multiple traits */
+    export type AddMulti<Tr extends readonly Any[], T> = T extends ErrorType<any> ? T : _AddMulti<Tr, HandleOriginalType<T>>;
+    /** Internal implementation of 'Trait.AddMulti' */
+    type _AddMulti<Tr extends readonly Any[], T> = WithMetadata<T, TraitsCore.FromMap<IfNever<TraitsCore.TraitsOf<T>> & IfNever<TraitsCore.TraitsOf<IntersectOf<Tr[number]>>>>>;
+    /** Remove a trait */
+    export type Drop<Tr extends Any, T> = T extends ErrorType<any> ? T : _Drop<Tr, HandleOriginalType<T>>;
+    /** Internal implementation of 'Trait.Drop' */
+    type _Drop<Tr extends Any, T> = Equals<TraitsCore.TraitKeysOf<Tr>, TraitsCore.TraitKeysOf<T>> extends true ? Equals<keyof PhantomCore.PhantomOf<T>, '__OriginalType' | '__Traits'> extends true ? PhantomCore.StripPhantom<T> : WithoutMetadata<T, '__Traits'> : WithMetadata<T, TraitsCore.FromMap<Omit<TraitsCore.TraitsOf<T>, TraitsCore.TraitKeysOf<Tr>>>>;
+    /** Remove multiple traits */
+    export type DropMulti<Tr extends readonly Any[], T> = T extends ErrorType<any> ? T : _DropMulti<Tr, HandleOriginalType<T>>;
+    /** Internal implementation of 'Trait.DropMulti' */
+    type _DropMulti<Tr extends readonly Any[], T> = Equals<TraitsCore.TraitKeysOf<IntersectOf<Tr[number]>>, TraitsCore.TraitKeysOf<T>> extends true ? Equals<keyof PhantomCore.PhantomOf<T>, '__OriginalType' | '__Traits'> extends true ? PhantomCore.StripPhantom<T> : WithoutMetadata<T, '__Traits'> : WithMetadata<T, TraitsCore.FromMap<Omit<TraitsCore.TraitsOf<T>, TraitsCore.TraitKeysOf<IntersectOf<Tr[number]>>>>>;
+    /** Check whether value has trait */
+    export type HasTrait<T, Tr extends Any> = T extends Tr ? true : false;
+    export {  };
+}
+
+/**
+ * Transformation API.
+ *
+ * Transformations represent reversible operations that
+ * change the shape of a value while preserving its origin.
+ */
+declare namespace TransformationCore {
+    /** Type guard for any transformation. */
+    export type Any = InputCore.Of<any> & TagCore.Of<string | symbol>;
+    /** Declare a transformation */
+    export type Declare<I, T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = Prettify<InputCore.Of<I> & TagCore.Of<T> & LabelCore.OfIfExists<L> & BaseCore.OfIfExists<B> & VariantsCore.OfIfExists<V>>;
+    /**
+     * Apply a transformation to a value.
+     * Enforces base-type compatibility.
+     */
+    export type Apply<Tr extends Any, I, T> = T extends ErrorType<any> ? T : _Apply<Tr, I, HandleOriginalType<T>>;
+    /** Internal implementation of 'Transformation.Apply' */
+    type _Apply<Tr extends Any, I, T> = TagCore.HasTag<T> extends true ? ErrorType<Errors<I, T>['alreadyBranded']> : T extends BaseCore.BaseOf<I> ? WithMetadata<T, PatchMetadata<Tr, InputCore.Of<I>>> : ErrorType<Errors<I, T>['typeNotExtendBase']>;
+    /** Revert a transformation */
+    export type Revert<Tr extends Any, T, I> = T extends ErrorType<any> ? T : _Revert<Tr, HandleOriginalType<T>, I>;
+    /** Internal implementation of 'Transformation.Revert' */
+    type _Revert<Tr extends Any, T, I> = InputCore.HasInput<T> extends true ? T extends Tr ? InputCore.InputOf<T> : ErrorType<Errors<Tr, T>['transformationMismatch']> : ErrorType<Errors<never, T>['notTransformed']>;
+    /** Revert a transformation whatever transformation was */
+    export type RevertAny<T, I> = T extends ErrorType<any> ? T : _RevertAny<HandleOriginalType<T>>;
+    /** Internal implementation of 'Transformation.RevertAny' */
+    type _RevertAny<T> = InputCore.HasInput<T> extends true ? InputCore.InputOf<T> : ErrorType<Errors<never, T>['notTransformed']>;
+    /** Check whether value is transformed with */
+    export type isTransformed<T, Tr extends Any> = T extends Tr ? true : false;
+    export {  };
+}
+
+/**
+ *
+ * This file define public aspect of fields and compesed types
+ *
+ */
+
+/**
+ * Optional human-readable label metadata.
+ *
+ * Labels are descriptive only and do not affect identity.
+ */
+declare namespace Label {
+    /** Marker type for labeled values */
+    type Any = LabelCore.Any;
+    /** Extract the label */
+    type LabelOf<T> = LabelCore.LabelOf<T>;
+    /** Check whether a label exists */
+    type HasLabel<T, L extends string = string> = LabelCore.HasLabel<T, L>;
+}
+/**
+ * Nominal tag metadata.
+ *
+ * Tags uniquely identify a branded or identified type.
+ * A value may only have a single tag.
+ */
+declare namespace Tag {
+    /** Marker type for any tagged value */
+    type Any = TagCore.Any;
+    /** Extract the tag from a type */
+    type TagOf<T> = TagCore.TagOf<T>;
+    /** Check whether a type is tagged */
+    type HasTag<T, Ta extends string | symbol = string | symbol> = TagCore.HasTag<T, Ta>;
+}
+/**
+ * Variant metadata.
+ *
+ * Variants represent mutually exclusive states of a type.
+ */
+declare namespace Variants {
+    /** Marker type for variant-bearing values */
+    type Any = VariantsCore.Any;
+    /** Extract variant union */
+    type VariantsOf<T> = VariantsCore.VariantsOf<T>;
+    /** Check whether variants exist */
+    type HasVariants<T> = VariantsCore.HasVariants<T>;
+}
+/**
+ * Base-type metadata.
+ *
+ * Used to constrain which runtime types a brand, identity,
+ * or transformation may be applied to.
+ */
+declare namespace Base {
+    /** Marker type for base constraints */
+    type Any = BaseCore.Any;
+    /** Extract the base type */
+    type BaseOf<T> = BaseCore.BaseOf<T>;
+    /** Check whether a base constraint exists */
+    type HasBase<T, B = unknown> = BaseCore.HasBase<T, B>;
+}
+/**
+ * Input metadata.
+ *
+ * Utilities for attaching and querying input metadata in transformations.
+ */
+declare namespace Input {
+    /** Marker type for input value */
+    type Any = InputCore.Any;
+    /** Extract the input */
+    type InputOf<T> = InputCore.InputOf<T>;
+    /** Check whether an input exists */
+    type HasInput<T, I = unknown> = InputCore.HasInput<T, I>;
+}
+/**
+ * Trait metadata.
+ *
+ * Traits behave like a set of capabilities that can be
+ * added or removed independently.
+ */
+declare namespace Traits {
+    /** Marker type for trait-bearing values */
+    type Any = TraitsCore.Any;
+    /** Extract the trait map */
+    type TraitsOf<T> = TraitsCore.TraitsOf<T>;
+    /** Extract trait keys */
+    type TraitKeysOf<T> = TraitsCore.TraitKeysOf<T>;
+    /** Check if any traits exist */
+    type HasTraits<T, Tr extends string | symbol = string | symbol> = TraitsCore.HasTraits<T, Tr>;
+}
+/**
+ * Branding API.
+ *
+ * Brands provide nominal typing for otherwise identical values.
+ * A value may only be branded once.
+ */
+declare namespace Brand {
+    /** Type guard for any brand. */
+    type Any = BrandCore.Any;
+    /** Declare a brand */
+    type Declare<T extends string | symbol, L extends string = never> = BrandCore.Declare<T, L>;
+    /** Assign a brand to a value. Fails if the value is already branded */
+    type Assign<B extends Any, T> = BrandCore.Assign<B, T>;
+    /** Assign a brand if possible, otherwise return the original type */
+    type AssignSafe<B extends Any, T> = BrandCore.AssignSafe<B, T>;
+    /** Check whether value is branded with */
+    type isBrand<T, B extends Any> = BrandCore.isBrand<T, B>;
+}
+/**
+ * Identity API.
+ *
+ * Identities are brands with additional constraints:
+ * - Base type
+ * - Variants
+ */
+declare namespace Identity {
+    /** Type guard for any identity. */
+    type Any = IdentityCore.Any;
+    /** Declare an identity */
+    type Declare<T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = IdentityCore.Declare<T, L, B, V>;
+    /** Assign an identity to a value. Enforces base-type compatibility */
+    type Assign<I extends Any, T> = IdentityCore.Assign<I, T>;
+    /** Safe identity assignment */
+    type AssignSafe<I extends Any, T> = IdentityCore.AssignSafe<I, T>;
+    /** Set the active variant on an identity */
+    type WithVariant<I extends Any, V extends Variants.VariantsOf<I>> = IdentityCore.WithVariant<I, V>;
+    /** Set the active variant on a value */
+    type WithTypeVariant<T, V extends Variants.VariantsOf<T>> = IdentityCore.WithTypeVariant<T, V>;
+    /** Check whether value is branded with */
+    type isIdentity<T, I extends Any> = IdentityCore.isIdentity<T, I>;
+}
+/**
+ * Trait API.
+ *
+ * Traits are additive capabilities that can be attached
+ * or removed independently.
+ */
+declare namespace Trait {
+    /** Type guard for any trait. */
+    type Any = TraitCore.Any;
+    /** Declare a trait */
+    type Declare<Tr extends string | symbol> = TraitCore.Declare<Tr>;
+    /** Add a trait */
+    type Add<Tr extends Any, T> = TraitCore.Add<Tr, T>;
+    /** Add multiple traits */
+    type AddMulti<Tr extends readonly Any[], T> = TraitCore.AddMulti<Tr, T>;
+    /** Remove a trait */
+    type Drop<Tr extends Any, T> = TraitCore.Drop<Tr, T>;
+    /** Remove multiple traits */
+    type DropMulti<Tr extends readonly Any[], T> = TraitCore.DropMulti<Tr, T>;
+    /** Check whether value has trait */
+    type HasTrait<T, Tr extends Any> = TraitCore.HasTrait<T, Tr>;
+}
+/**
+ * Transformation API.
+ *
+ * Transformations represent reversible operations that
+ * change the shape of a value while preserving its origin.
+ */
+declare namespace Transformation {
+    /** Type guard for any transformation. */
+    type Any = TransformationCore.Any;
+    /** Declare a transformation */
+    type Declare<I, T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = TransformationCore.Declare<I, T, L, B, V>;
+    /** Apply a transformation to a value. Enforces base-type compatibility */
+    type Apply<Tr extends Any, I, T> = TransformationCore.Apply<Tr, I, T>;
+    /** Revert a transformation */
+    type Revert<Tr extends Any, T, I> = TransformationCore.Revert<Tr, T, I>;
+    /** Revert a transformation whatever transformation was */
+    type RevertAny<T, I> = TransformationCore.RevertAny<T, I>;
+    /** Check whether value is transformed with */
+    type isTransformed<T, Tr extends Any> = TransformationCore.isTransformed<T, Tr>;
+}
+
+/**
+ * Inspect API.
+ *
+ * Inspection helpers of phantom types.
+ */
+declare namespace Inspect {
+    /** Extract the label */
+    type LabelOf<T> = LabelCore.LabelOf<T>;
+    /** Check whether a base constraint exists */
+    type HasLabel<T, L extends string = string> = LabelCore.HasLabel<T, L>;
+    /** Extract the tag from a type */
+    type TagOf<T> = TagCore.TagOf<T>;
+    /** Check whether a type is tagged */
+    type HasTag<T, Ta extends string | symbol = string | symbol> = TagCore.HasTag<T, Ta>;
+    /** Extract variant union */
+    type VariantsOf<T> = VariantsCore.VariantsOf<T>;
+    /** Check whether variants exist */
+    type HasVariants<T> = VariantsCore.HasVariants<T>;
+    /** Extract the base type */
+    type BaseOf<T> = BaseCore.BaseOf<T>;
+    /** Check whether a base constraint exists */
+    type HasBase<T, B = unknown> = BaseCore.HasBase<T, B>;
+    /** Extract the input */
+    type InputOf<T> = InputCore.InputOf<T>;
+    /** Check whether an input exists */
+    type HasInput<T, I = unknown> = InputCore.HasInput<T, I>;
+    /** Extract the trait map */
+    type TraitsOf<T> = TraitsCore.TraitsOf<T>;
+    /** Extract trait keys */
+    type TraitKeysOf<T> = TraitsCore.TraitKeysOf<T>;
+    /** Check if any traits exist */
+    type HasTraits<T> = TraitsCore.HasTraits<T>;
+    /** Check whether value is branded with */
+    type isBrand<T, B extends BrandCore.Any> = BrandCore.isBrand<T, B>;
+    /** Check whether value is branded with */
+    type isIdentity<T, I extends IdentityCore.Any> = IdentityCore.isIdentity<T, I>;
+    /** Check whether value has trait */
+    type HasTrait<T, Tr extends TraitCore.Any> = TraitCore.HasTrait<T, Tr>;
+    /** Check whether value is transformed with */
+    type isTransformed<T, Tr extends TransformationCore.Any> = TransformationCore.isTransformed<T, Tr>;
+}
+
+/**
+ * Creates a typed caster that assigns a {@link Brand} to a value.
+ *
+ * This is a zero-cost runtime assertion helper — it simply returns the value
+ * with the brand's nominal type applied. Use it for simple branded primitives
+ * where you know the value is valid.
+ *
+ * @template B - The brand declaration to assign.
+ * @returns A function that casts any value to the branded type.
+ */
+declare const asBrand: <B extends Brand.Any>() => <T>(value: T) => Brand.Assign<B, T>;
+
+/**
+ * Creates a typed caster that assigns an {@link Identity} to a value.
+ *
+ * This is a zero-cost runtime assertion helper — it simply returns the value
+ * with the identity's nominal type applied. Use it when you know a value
+ * conforms to an identity but need to assert it for the type system.
+ *
+ * @template I - The identity declaration to assign.
+ * @returns A function that casts any value to the assigned identity type.
+ */
+declare const asIdentity: <I extends Identity.Any>() => <V>(value: V) => Identity.Assign<I, V>;
+
+/**
+ * Creates a typed caster that adds a single {@link Trait} to a value.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - The trait declaration to add.
+ * @returns A function that adds the trait to any value.
+ */
+declare const addTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Add<Tr, V>;
+/**
+ * Creates a typed caster that adds multiple {@link Trait}s to a value.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - Tuple of trait declarations to add.
+ * @returns A function that adds all traits to any value.
+ */
+declare const addTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.AddMulti<Tr, V>;
+/**
+ * Creates a typed caster that removes a single {@link Trait} from a value.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - The trait declaration to remove.
+ * @returns A function that drops the trait from any value.
+ */
+declare const dropTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Drop<Tr, V>;
+/**
+ * Creates a typed caster that removes multiple {@link Trait}s from a value.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - Tuple of trait declarations to remove.
+ * @returns A function that drops all specified traits from any value.
+ */
+declare const dropTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.DropMulti<Tr, V>;
+
+/**
+ * Creates a typed applicator for a {@link Transformation}.
+ *
+ * Use this for "forward" operations (e.g., encrypt, encode, wrap).
+ * The `input` parameter is only used for type inference — it is not used at runtime.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - The transformation declaration.
+ * @returns A function that applies the transformation while preserving the input type for later revert.
+ */
+declare const applyTransformation: <Tr extends Transformation.Any>() => <I, T>(input: I, transformed: T) => Transformation.Apply<Tr, I, T>;
+/**
+ * Creates a typed reverter for a {@link Transformation}.
+ *
+ * Use this for "reverse" operations (e.g., decrypt, decode, unwrap).
+ * The `transformed` parameter is used for type inference of the expected input,
+ * and `input` is the computed result that must match the stored input type.
+ *
+ * Zero-runtime-cost assertion helper.
+ *
+ * @template Tr - The transformation declaration.
+ * @returns A function that reverts the transformation, stripping phantom metadata.
+ */
+declare const revertTransformation: <Tr extends Transformation.Any>() => <T, I>(transformed: T, input: I) => Transformation.Revert<Tr, T, I>;
+
+/**
+ * A fluent PhantomChain class for chaining Phantom assertors.
+ *
+ * This provides a better developer experience (DX) by allowing method chaining
+ * with `.with(assertor)` instead of nesting function calls or using a variadic chain.
+ * Each `.with()` applies the assertor to the current value, updating the type incrementally.
+ * Call `.end()` to retrieve the final value.
+ *
+ * At runtime, assertors are zero-cost casts, so the PhantomChain adds minimal overhead
+ * (just object creation and method calls).
+ *
+ * Example:
+ * ```ts
+ * const asMyBrand = Phantom.assertors.asBrand<MyBrand>();
+ * const asMyTrait = Phantom.assertors.asTrait<MyTrait>();
+ * const applyMyTransform = Phantom.assertors.applyTransformation<MyTransform>();
+ *
+ * const result = new PhantomChain("value")
+ *   .with(asMyBrand)
+ *   .with(asMyTrait)
+ *   .with(applyMyTransform)
+ *   .end();
+ * ```
+ */
+declare class PhantomChain<T> {
+    private value;
+    constructor(value: T);
+    /**
+     * Apply the next assertor in the chain.
+     *
+     * @param assertor A function that takes the current value and returns the updated value (with new type).
+     * @returns A new PhantomChain instance with the updated value and type.
+     */
+    with<U>(assertor: (value: T) => U): PhantomChain<U>;
+    /**
+     * End the chain and return the final value.
+     *
+     * @returns The value after all transformations.
+     */
+    end(): T;
+}
+
+declare const _PhantomChain: typeof PhantomChain;
+type _ErrorType<E> = ErrorType<E>;
+declare namespace Phantom {
+    /** --------------------------------------
+     * Types
+     * --------------------------------------- */
+    /**
+     * Optional human-readable label metadata.
+     *
+     * Labels are descriptive only and do not affect identity.
+     */
+    namespace Label {
+        /** Marker type for labeled values */
+        type Any = LabelCore.Any;
+        /** Extract the label */
+        type LabelOf<T> = LabelCore.LabelOf<T>;
+        /** Check whether a label exists */
+        type HasLabel<T, L extends string = string> = LabelCore.HasLabel<T, L>;
+    }
+    /**
+     * Nominal tag metadata.
+     *
+     * Tags uniquely identify a branded or identified type.
+     * A value may only have a single tag.
+     */
+    namespace Tag {
+        /** Marker type for any tagged value */
+        type Any = TagCore.Any;
+        /** Extract the tag from a type */
+        type TagOf<T> = TagCore.TagOf<T>;
+        /** Check whether a type is tagged */
+        type HasTag<T, Ta extends string | symbol = string | symbol> = TagCore.HasTag<T, Ta>;
+    }
+    /**
+     * Variant metadata.
+     *
+     * Variants represent mutually exclusive states of a type.
+     */
+    namespace Variants {
+        /** Marker type for variant-bearing values */
+        type Any = VariantsCore.Any;
+        /** Extract variant union */
+        type VariantsOf<T> = VariantsCore.VariantsOf<T>;
+        /** Check whether variants exist */
+        type HasVariants<T> = VariantsCore.HasVariants<T>;
+    }
+    /**
+     * Base-type metadata.
+     *
+     * Used to constrain which runtime types a brand, identity,
+     * or transformation may be applied to.
+     */
+    namespace Base {
+        /** Marker type for base constraints */
+        type Any = BaseCore.Any;
+        /** Extract the base type */
+        type BaseOf<T> = BaseCore.BaseOf<T>;
+        /** Check whether a base constraint exists */
+        type HasBase<T, B = unknown> = BaseCore.HasBase<T, B>;
+    }
+    /**
+     * Input metadata.
+     *
+     * Utilities for attaching and querying input metadata in transformations.
+     */
+    namespace Input {
+        /** Marker type for input value */
+        type Any = InputCore.Any;
+        /** Extract the input */
+        type InputOf<T> = InputCore.InputOf<T>;
+        /** Check whether an input exists */
+        type HasInput<T, I = unknown> = InputCore.HasInput<T, I>;
+    }
+    /**
+     * Trait metadata.
+     *
+     * Traits behave like a set of capabilities that can be
+     * added or removed independently.
+     */
+    namespace Traits {
+        /** Marker type for trait-bearing values */
+        type Any = TraitsCore.Any;
+        /** Extract the trait map */
+        type TraitsOf<T> = TraitsCore.TraitsOf<T>;
+        /** Extract trait keys */
+        type TraitKeysOf<T> = TraitsCore.TraitKeysOf<T>;
+        /** Check if any traits exist */
+        type HasTraits<T, Tr extends string | symbol = string | symbol> = TraitsCore.HasTraits<T, Tr>;
+    }
+    /**
+     * Branding API.
+     *
+     * Brands provide nominal typing for otherwise identical values.
+     * A value may only be branded once.
+     */
+    namespace Brand {
+        /** Type guard for any brand. */
+        type Any = BrandCore.Any;
+        /** Declare a brand */
+        type Declare<T extends string | symbol, L extends string = never> = BrandCore.Declare<T, L>;
+        /** Assign a brand to a value. Fails if the value is already branded */
+        type Assign<B extends Any, T> = BrandCore.Assign<B, T>;
+        /** Assign a brand if possible, otherwise return the original type */
+        type AssignSafe<B extends Any, T> = BrandCore.AssignSafe<B, T>;
+        /** Check whether value is branded with */
+        type isBrand<T, B extends Brand.Any> = BrandCore.isBrand<T, B>;
+    }
+    /**
+     * Identity API.
+     *
+     * Identities are brands with additional constraints:
+     * - Base type
+     * - Variants
+     */
+    namespace Identity {
+        /** Type guard for any identity. */
+        type Any = IdentityCore.Any;
+        /** Declare an identity */
+        type Declare<T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = IdentityCore.Declare<T, L, B, V>;
+        /** Assign an identity to a value. Enforces base-type compatibility */
+        type Assign<I extends Any, T> = IdentityCore.Assign<I, T>;
+        /** Safe identity assignment */
+        type AssignSafe<I extends Any, T> = IdentityCore.AssignSafe<I, T>;
+        /** Set the active variant on an identity */
+        type WithVariant<I extends Any, V extends Variants.VariantsOf<I>> = IdentityCore.WithVariant<I, V>;
+        /** Set the active variant on a value */
+        type WithTypeVariant<T, V extends Variants.VariantsOf<T>> = IdentityCore.WithTypeVariant<T, V>;
+        /** Check whether value is branded with */
+        type isIdentity<T, I extends Any> = IdentityCore.isIdentity<T, I>;
+    }
+    /**
+     * Trait API.
+     *
+     * Traits are additive capabilities that can be attached
+     * or removed independently.
+     */
+    namespace Trait {
+        /** Type guard for any trait. */
+        type Any = TraitCore.Any;
+        /** Declare a trait */
+        type Declare<Tr extends string | symbol> = TraitCore.Declare<Tr>;
+        /** Add a trait */
+        type Add<Tr extends Any, T> = TraitCore.Add<Tr, T>;
+        /** Add multiple traits */
+        type AddMulti<Tr extends readonly Any[], T> = TraitCore.AddMulti<Tr, T>;
+        /** Remove a trait */
+        type Drop<Tr extends Any, T> = TraitCore.Drop<Tr, T>;
+        /** Remove multiple traits */
+        type DropMulti<Tr extends readonly Any[], T> = TraitCore.DropMulti<Tr, T>;
+        /** Check whether value has trait */
+        type HasTrait<T, Tr extends Any> = TraitCore.HasTrait<T, Tr>;
+    }
+    /**
+     * Transformation API.
+     *
+     * Transformations represent reversible operations that
+     * change the shape of a value while preserving its origin.
+     */
+    namespace Transformation {
+        /** Type guard for any transformation. */
+        type Any = TransformationCore.Any;
+        /** Declare a transformation */
+        type Declare<I, T extends string | symbol, L extends string = never, B extends unknown = never, V extends string = never> = TransformationCore.Declare<I, T, L, B, V>;
+        /** Apply a transformation to a value. Enforces base-type compatibility */
+        type Apply<Tr extends Any, I, T> = TransformationCore.Apply<Tr, I, T>;
+        /** Revert a transformation */
+        type Revert<Tr extends Any, T, I> = TransformationCore.Revert<Tr, T, I>;
+        /** Revert a transformation whatever transformation was */
+        type RevertAny<T, I> = TransformationCore.RevertAny<T, I>;
+        /** Check whether value is transformed with */
+        type isTransformed<T, Tr extends Any> = TransformationCore.isTransformed<T, Tr>;
+    }
+    /**
+     * Inspect API.
+     *
+     * Inspection helpers of phantom types.
+     */
+    namespace Inspect {
+        /** Get phantom metadata object from a type */
+        type PhantomOf<T> = PhantomCore.PhantomOf<T>;
+        /** Stip phantom metadata object from a type */
+        type StripPhantom<T> = PhantomCore.StripPhantom<T>;
+        /** run-time helper for 'StringPhantom', used for debugging mainly */
+        const stripPhantom: <T>(value: T) => PhantomCore.StripPhantom<T>;
+        /** Extract the label */
+        type LabelOf<T> = LabelCore.LabelOf<T>;
+        /** Check whether a base constraint exists */
+        type HasLabel<T, L extends string = string> = LabelCore.HasLabel<T, L>;
+        /** Extract the tag from a type */
+        type TagOf<T> = TagCore.TagOf<T>;
+        /** Check whether a type is tagged */
+        type HasTag<T, Ta extends string | symbol = string | symbol> = TagCore.HasTag<T, Ta>;
+        /** Extract variant union */
+        type VariantsOf<T> = VariantsCore.VariantsOf<T>;
+        /** Check whether variants exist */
+        type HasVariants<T> = VariantsCore.HasVariants<T>;
+        /** Extract the base type */
+        type BaseOf<T> = BaseCore.BaseOf<T>;
+        /** Check whether a base constraint exists */
+        type HasBase<T, B = unknown> = BaseCore.HasBase<T, B>;
+        /** Extract the input */
+        type InputOf<T> = InputCore.InputOf<T>;
+        /** Check whether an input exists */
+        type HasInput<T, I = unknown> = InputCore.HasInput<T, I>;
+        /** Extract the trait map */
+        type TraitsOf<T> = TraitsCore.TraitsOf<T>;
+        /** Extract trait keys */
+        type TraitKeysOf<T> = TraitsCore.TraitKeysOf<T>;
+        /** Check if any traits exist */
+        type HasTraits<T, Tr extends string | symbol = string | symbol> = TraitsCore.HasTraits<T, Tr>;
+        /** Check whether value is branded with */
+        type isBrand<T, B extends Brand.Any> = BrandCore.isBrand<T, B>;
+        /** Check whether value is branded with */
+        type isIdentity<T, I extends Identity.Any> = IdentityCore.isIdentity<T, I>;
+        /** Check whether value has trait */
+        type HasTrait<T, Tr extends Trait.Any> = TraitCore.HasTrait<T, Tr>;
+        /** Check whether value is transformed with */
+        type isTransformed<T, Tr extends Transformation.Any> = TransformationCore.isTransformed<T, Tr>;
+    }
+    /** --------------------------------------
+     * assertors
+     * --------------------------------------- */
+    namespace assertors {
+        /**
+         * Creates a typed caster that assigns a {@link Brand} to a value.
+         *
+         * This is a zero-cost runtime assertion helper — it simply returns the value
+         * with the brand's nominal type applied. Use it for simple branded primitives
+         * where you know the value is valid.
+         *
+         * @template B - The brand declaration to assign.
+         * @returns A function that casts any value to the branded type.
+         */
+        const asBrand: <B extends Brand.Any>() => <T>(value: T) => Brand.Assign<B, T>;
+        /**
+         * Creates a typed caster that assigns an {@link Identity} to a value.
+         *
+         * This is a zero-cost runtime assertion helper — it simply returns the value
+         * with the identity's nominal type applied. Use it when you know a value
+         * conforms to an identity but need to assert it for the type system.
+         *
+         * @template I - The identity declaration to assign.
+         * @returns A function that casts any value to the assigned identity type.
+         */
+        const asIdentity: <I extends Identity.Any>() => <V>(value: V) => Identity.Assign<I, V>;
+        /**
+         * Creates a typed caster that adds a single {@link Trait} to a value.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - The trait declaration to add.
+         * @returns A function that adds the trait to any value.
+         */
+        const addTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Add<Tr, V>;
+        /**
+         * Creates a typed caster that adds multiple {@link Trait}s to a value.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - Tuple of trait declarations to add.
+         * @returns A function that adds all traits to any value.
+         */
+        const addTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.AddMulti<Tr, V>;
+        /**
+         * Creates a typed caster that removes a single {@link Trait} from a value.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - The trait declaration to remove.
+         * @returns A function that drops the trait from any value.
+         */
+        const dropTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Drop<Tr, V>;
+        /**
+         * Creates a typed caster that removes multiple {@link Trait}s from a value.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - Tuple of trait declarations to remove.
+         * @returns A function that drops all specified traits from any value.
+         */
+        const dropTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.DropMulti<Tr, V>;
+        /**
+         * Creates a typed applicator for a {@link Transformation}.
+         *
+         * Use this for "forward" operations (e.g., encrypt, encode, wrap).
+         * The `input` parameter is only used for type inference — it is not used at runtime.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - The transformation declaration.
+         * @returns A function that applies the transformation while preserving the input type for later revert.
+         */
+        const applyTransformation: <Tr extends Transformation.Any>() => <I, T>(input: I, transformed: T) => Transformation.Apply<Tr, I, T>;
+        /**
+         * Creates a typed reverter for a {@link Transformation}.
+         *
+         * Use this for "reverse" operations (e.g., decrypt, decode, unwrap).
+         * The `transformed` parameter is used for type inference of the expected input,
+         * and `input` is the computed result that must match the stored input type.
+         *
+         * Zero-runtime-cost assertion helper.
+         *
+         * @template Tr - The transformation declaration.
+         * @returns A function that reverts the transformation, stripping phantom metadata.
+         */
+        const revertTransformation: <Tr extends Transformation.Any>() => <T, I>(transformed: T, input: I) => Transformation.Revert<Tr, T, I>;
+    }
+    /**
+     * Creates a typed caster that assigns a {@link Brand} to a value.
+     *
+     * This is a zero-cost runtime assertion helper — it simply returns the value
+     * with the brand's nominal type applied. Use it for simple branded primitives
+     * where you know the value is valid.
+     *
+     * @template B - The brand declaration to assign.
+     * @returns A function that casts any value to the branded type.
+     */
+    const asBrand: <B extends Brand.Any>() => <T>(value: T) => Brand.Assign<B, T>;
+    /**
+     * Creates a typed caster that assigns an {@link Identity} to a value.
+     *
+     * This is a zero-cost runtime assertion helper — it simply returns the value
+     * with the identity's nominal type applied. Use it when you know a value
+     * conforms to an identity but need to assert it for the type system.
+     *
+     * @template I - The identity declaration to assign.
+     * @returns A function that casts any value to the assigned identity type.
+     */
+    const asIdentity: <I extends Identity.Any>() => <V>(value: V) => Identity.Assign<I, V>;
+    /**
+     * Creates a typed caster that adds a single {@link Trait} to a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The trait declaration to add.
+     * @returns A function that adds the trait to any value.
+     */
+    const addTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Add<Tr, V>;
+    /**
+     * Creates a typed caster that adds multiple {@link Trait}s to a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - Tuple of trait declarations to add.
+     * @returns A function that adds all traits to any value.
+     */
+    const addTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.AddMulti<Tr, V>;
+    /**
+     * Creates a typed caster that removes a single {@link Trait} from a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The trait declaration to remove.
+     * @returns A function that drops the trait from any value.
+     */
+    const dropTrait: <Tr extends Trait.Any>() => <V>(value: V) => Trait.Drop<Tr, V>;
+    /**
+     * Creates a typed caster that removes multiple {@link Trait}s from a value.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - Tuple of trait declarations to remove.
+     * @returns A function that drops all specified traits from any value.
+     */
+    const dropTraits: <Tr extends Trait.Any[]>() => <V>(value: V) => Trait.DropMulti<Tr, V>;
+    /**
+     * Creates a typed applicator for a {@link Transformation}.
+     *
+     * Use this for "forward" operations (e.g., encrypt, encode, wrap).
+     * The `input` parameter is only used for type inference — it is not used at runtime.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The transformation declaration.
+     * @returns A function that applies the transformation while preserving the input type for later revert.
+     */
+    const applyTransformation: <Tr extends Transformation.Any>() => <I, T>(input: I, transformed: T) => Transformation.Apply<Tr, I, T>;
+    /**
+     * Creates a typed reverter for a {@link Transformation}.
+     *
+     * Use this for "reverse" operations (e.g., decrypt, decode, unwrap).
+     * The `transformed` parameter is used for type inference of the expected input,
+     * and `input` is the computed result that must match the stored input type.
+     *
+     * Zero-runtime-cost assertion helper.
+     *
+     * @template Tr - The transformation declaration.
+     * @returns A function that reverts the transformation, stripping phantom metadata.
+     */
+    const revertTransformation: <Tr extends Transformation.Any>() => <T, I>(transformed: T, input: I) => Transformation.Revert<Tr, T, I>;
+    /** --------------------------------------
+     * Phantom object manipulators
+     * --------------------------------------- */
+    /** Get phantom metadata object from a type */
+    type PhantomOf<T> = PhantomCore.PhantomOf<T>;
+    /** Stip phantom metadata object from a type */
+    type StripPhantom<T> = PhantomCore.StripPhantom<T>;
+    /** run-time helper for 'StringPhantom', used for debugging mainly */
+    const stripPhantom: <T>(value: T) => PhantomCore.StripPhantom<T>;
+    /** --------------------------------------
+     * Error type
+     * --------------------------------------- */
+    /** Unique Error type for rules validation in phantom. */
+    type ErrorType<E> = _ErrorType<E>;
+    /** --------------------------------------
+     * Chain class
+     * --------------------------------------- */
+    /**
+     * A fluent PhantomChain class for chaining Phantom assertors.
+     *
+     * This provides a better developer experience (DX) by allowing method chaining
+     * with `.with(assertor)` instead of nesting function calls or using a variadic chain.
+     * Each `.with()` applies the assertor to the current value, updating the type incrementally.
+     * Call `.end()` to retrieve the final value.
+     *
+     * At runtime, assertors are zero-cost casts, so the PhantomChain adds minimal overhead
+     * (just object creation and method calls).
+     *
+     * Example:
+     * ```ts
+     * const asMyBrand = Phantom.assertors.asBrand<MyBrand>();
+     * const asMyTrait = Phantom.assertors.asTrait<MyTrait>();
+     * const applyMyTransform = Phantom.assertors.applyTransformation<MyTransform>();
+     *
+     * const result = new PhantomChain("value")
+     *   .with(asMyBrand)
+     *   .with(asMyTrait)
+     *   .with(applyMyTransform)
+     *   .end();
+     * ```
+     */
+    class PhantomChain<T> extends _PhantomChain<T> {
+    }
+}
+
+export { Base, Brand, type ErrorType, Identity, Input, Inspect, Label, Phantom, PhantomChain, PhantomCore, Tag, Trait, Traits, Transformation, Variants, addTrait, addTraits, applyTransformation, asBrand, asIdentity, assertors, Phantom as default, dropTrait, dropTraits, revertTransformation };