@vicin/sigil 2.0.3 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.1] - 2026-02-23
+
+### Added
+
+- `SigilEffectiveLabel`/`getSigilEffectiveLabel()` which are last passed label for logging purposes.
+
+### Changed
+
+- Patched multiple bugs.
+- Updated defualt options, now `SigilOptions.autofillLabels` is `true` by default.
+
+## [2.1.0] - 2026-02-22
+
+### Changed
+
+- Changed name of `updateOptions` to be `updateSigilOptions`
+- Updated JSDOCs of multiple APIs
+
 ## [2.0.3] - 2026-02-21
 
 - Patched types
@@ -26,19 +44,19 @@ All notable changes to this project will be documented in this file.
 
 ### Breaking changes
 
-- All `SigilRegistry`options, methods and classes are removed.
+- All `SigilRegistry`options, methods and classes are removed
 
 ## [1.3.0] - 2026-02-18
 
 ### Added
 
-- `isOfType()` & `isOfTypeStrict()` now can be called from instances.
+- `isOfType()` & `isOfTypeStrict()` now can be called from instances
 
 ## [1.2.7] - 2026-02-13
 
 ### Added
 
-- Support for `abstract` classes using `SigilifyAbstract` factory.
+- Support for `abstract` classes using `SigilifyAbstract` factory
 
 ## [1.2.6] - 2026-02-11
 

package/README.md

@@ -5,12 +5,12 @@
 > - 🎉 v2.0.0 is out! Happy coding! 😄💻
 > - 📄 **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
-`Sigil` is a lightweight TypeScript library for creating nominal identity classes with compile-time branding and reliable runtime type checks. It organizes class identities across your codebase and gives you the power of **nominal typing** and **safe cross-bundle class checks** where each class constructor is stored under a unique label.
+`Sigil` replaces `instanceof` across bundles, enforces nominal class identity, and makes inheritance-aware runtime type checks reliable in large TypeScript systems. It organizes class identities across your codebase and gives you the power of **nominal typing** and **safe cross-bundle class checks** where each class constructor is stored under a unique label.
 
 > **Key ideas:**
 >
+> - **Reliable Runtime Checks:** Uses labels instead of instanceof for cross-bundle reliability.
 > - **Nominal Typing at Compile Time:** Distinguishes structurally similar types (e.g., UserId vs. PostId).
-> - **Reliable Runtime Checks:** Uses symbols instead of instanceof for cross-bundle reliability.
 > - **Inheritance Awareness:** Tracks lineages for subtype/supertype checks.
 
 ## Important Notes Before Using
@@ -22,7 +22,7 @@
 
 ## Why Registry is dropped
 
-Although registry added label checks and central class management but it also introduced complexity, especially when mutiple packages tried to use it simultaneously, So in v2 we decided to omit it entirely and minimize API surface.
+In v2 we simplified the architecture to remove global registries and reduce complexity across packages.
 
 ---
 
@@ -48,8 +48,9 @@ Although registry added label checks and central class management but it also in
 - [API reference](#api-reference)
 - [Options & configuration](#options--configuration)
 - [Minimal mode](#minimal-mode)
+- [Strict mode](#strict-mode)
+- [## Which pattern should I use?](#which-pattern-should-i-use)
 - [Troubleshooting & FAQ](#troubleshooting--faq)
-- [Phantom](#phantom)
 - [Contributing](#contributing)
 - [License](#license)
 - [Author](#author)
@@ -151,16 +152,9 @@ console.log(User.isOfType(u)); // true
 
 ### Migration
 
-Migrating old code into `Sigil` can be done seamlessly with this set-up:
+Migrating old code into `Sigil` can be done with extra couple lines of code only:
 
-1. Set `SigilOptions.autofillLabels` to `true` at the start of the app so no errors are thrown in the migration stage:
-
-```ts
-import { updateOptions } from '@vicin/sigil';
-updateOptions({ autofillLabels: true });
-```
-
-2. Pass your base class to `Sigilify` mixin:
+1. Pass your base class to `Sigilify` mixin:
 
 ```ts
 import { Sigilify } from '@vicin/sigil';
@@ -168,7 +162,7 @@ import { Sigilify } from '@vicin/sigil';
 const MySigilBaseClass = Sigilify(MyBaseClass);
 ```
 
-3. Or extend it with `Sigil`:
+2. Or extend it with `Sigil`:
 
 ```ts
 import { Sigil } from '@vicin/sigil';
@@ -186,11 +180,9 @@ This section states clearly what `Sigil` provides and what it does **not** provi
 
 ### What Sigil guarantees
 
-**1. Stable label → symbol mapping within the same JS global symbol registry.**
+**1. Reliable runtime identity (when used as intended).**
 
-**2. Reliable runtime identity (when used as intended).**
-
-**3. Nominal typing that is inheritance-aware**
+**2. Nominal typing that is inheritance-aware**
 
 ### What Sigil does not guarantee
 
@@ -204,10 +196,10 @@ This section states clearly what `Sigil` provides and what it does **not** provi
 
 ### Terminology
 
-- **Label**: A human-readable identity (string) such as `@scope/pkg.ClassName`.
-- **SigilType (symbol)**: `Symbol.for(label)` — for runtime stability.
-- **Type lineage**: Array of symbols for ancestry.
-- **Type set**: Set of symbols for fast checks.
+- **Label**: An identity (string) such as `@scope/pkg.ClassName`, but can be random string (e.g. `@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h`) if no label passed.
+- **EffictiveLabel:** A human-readable (string) such as `@scope/pkg.ClassName`, if no label is passed it inherit the last defined label.
+- **Label lineage**: Array of labels for ancestry.
+- **Label set**: Set of labels for fast checks.
 - **Brand**: TypeScript marker (`__SIGIL_BRAND__`) for nominal types.
 
 ---
@@ -217,6 +209,15 @@ This section states clearly what `Sigil` provides and what it does **not** provi
 Sigil addresses issues in large monorepos and Domain-Driven Design (DDD):
 
 - **Unreliable `instanceof`:** Bundling and HMR cause class redefinitions, breaking checks.
+
+```ts
+// Broken in monorepo or HMR
+if (obj instanceof User) { ... }
+
+// With Sigil
+if (User.isOfType(obj)) { ... } // This still works even if User was bundled twice.
+```
+
 - **Manual Branding Overhead:** Custom identifiers lead to boilerplate and maintenance issues.
 
 `Sigil` abstracts these into a **centralized system**, making identity management **explicit** and **error-resistant** if defined the right way.
@@ -225,7 +226,7 @@ Sigil addresses issues in large monorepos and Domain-Driven Design (DDD):
 
 - **Runtime Contract:** Established via extending `Sigil` or using `Sigilify` mixin.
 - **Update metadata:** With each new child, HOF or decorators are used to attach metadata and update nominal type.
-- **Accessors & Type guards:** Classes expose `SigilLabel`, `SigilType`; instances provide `getSigilLabel()` and `getSigilType()` for querying unique identifier label or symbol. also when typed it hold nominal identity used to prevent subtle bugs.
+- **Accessors & Type guards:** Classes expose `SigilLabel`; instances provide `getSigilLabel()` for querying unique identifier label. also when typed it hold nominal identity used to prevent subtle bugs.
 
 ```ts
 import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
@@ -239,9 +240,9 @@ type MyClass = GetInstance<typeof MyClass>;
 
 // Accessors & Type guards
 console.log(MyClass.SigilLabel); // '@scope/package.MyClass'
-console.log(new MyClass().getSigilType()); // Symbol.for('@scope/package.MyClass')
+console.log(new MyClass().getSigilLabel()); // '@scope/package.MyClass'
 console.log(MyClass.isOfType(new MyClass())); // true
-function x(c: MyClass) {} // Only instances created by 'MyClass' can be passed
+function x(c: MyClass) {} // Only instances of 'MyClass' can be passed
 ```
 
 ---
@@ -315,7 +316,7 @@ type Y = GetInstance<typeof Y>;
 const y = new Y(); // <-- Type here is any
 ```
 
-Unfortunately this is a limitation in typescript and I couldn't find any solution to address it.
+This is a known TypeScript limitation.
 
 ---
 
@@ -384,7 +385,7 @@ class X extends Sigil {
   - `isInheritanceChecked(ctor)`
 
 - **Options:**
-  - `updateOptions(opts)`
+  - `updateSigilOptions(opts)`
   - `DEFAULT_LABEL_REGEX`
 
 - **Types:**
@@ -407,14 +408,15 @@ class X extends Sigil {
 - `withSigilTyped(Class, label?, opts?)`: like `withSigil` but narrows the TypeScript type to include brands.
 - `isSigilCtor(value)`: `true` if `value` is a `Sigil` constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a `Sigil` constructor.
-- `updateOptions(opts)`: change global runtime options before `Sigil` decoration (e.g., `autofillLabels`).
+- `updateSigilOptions(opts)`: change global runtime options before `Sigil` decoration (e.g., `autofillLabels`).
 - `DEFAULT_LABEL_REGEX`: regex that ensures structure of `@scope/package.ClassName` to all labels, it's advised to use it as your `SigilOptions.labelValidation`
 
 ### Instance & static helpers provided by Sigilified constructors
 
 When a constructor is decorated/sigilified it will expose the following **static** getters/methods:
 
-- `SigilLabel` — the human label string.
+- `SigilLabel` — the identity label string.
+- `SigilEffectiveLabel` — the human label string.
 - `SigilLabelLineage` — readonly array of labels representing parent → child.
 - `SigilLabelSet` — readonly `Set<string>` for O(1) checks.
 - `isSigilified(obj)` — runtime predicate that delegates to `isSigilInstance`.
@@ -423,10 +425,10 @@ When a constructor is decorated/sigilified it will expose the following **static
 
 Instances of sigilified classes expose instance helpers:
 
-- `getSigilLabel()` — returns the human label.
-- `getSigilType()` — runtime symbol.
-- `getSigilTypeLineage()` — returns lineage array.
-- `getSigilTypeSet()` — returns readonly Set.
+- `getSigilLabel()` — returns the identity label.
+- `getSigilEffectiveLabel()` — returns the human label.
+- `getSigilLabelLineage()` — returns lineage array.
+- `getSigilLabelSet()` — returns readonly Set.
 - `isOfType(other)` — O(1) membership test using `other`'s `__LABEL_SET__`.
 - `isOfTypeStrict(other)` — strict lineage comparison element-by-element.
 
@@ -437,11 +439,11 @@ Instances of sigilified classes expose instance helpers:
 Customize behavior globally at startup:
 
 ```ts
-import { updateOptions } from '@vicin/sigil';
+import { updateSigilOptions } from '@vicin/sigil';
 
-updateOptions({
-  autofillLabels: false, // Automatically label unlabeled subclasses
-  skipLabelInheritanceCheck: false, // Bypass dev inheritance checks -- ALMOST NEVER WANT TO SET THIS TO TRUE, Use 'autofillLabels: true' instead.
+updateSigilOptions({
+  autofillLabels: true, // Automatically label unlabeled subclasses
+  skipLabelInheritanceCheck: false, // Bypass dev inheritance checks -- ALMOST NEVER WANT TO SET THIS TO TRUE
   labelValidation: null, // Function or regex, Enforce label format
 });
 ```
@@ -452,13 +454,10 @@ Values defined in previous example are defaults, per-class overrides available i
 
 ## Minimal mode
 
-`updateOptions({ autofillLabels: true });` – Enables background operation without explicit labels:
+You can ignore all decorators and HOFs and just make base class extend `Sigil`:
 
 ```ts
-import { Sigil, updateOptions } from '@vicin/sigil';
-
-// run at the start of the app
-updateOptions({ autofillLabels: true });
+import { Sigil, updateSigilOptions } from '@vicin/sigil';
 
 // No decorators or HOF needed to use 'isOfType' ('instanceof' replacement)
 class A extends Sigil {}
@@ -466,24 +465,34 @@ class B extends A {}
 class C extends B {}
 ```
 
----
+## Strict mode
 
-## Troubleshooting & FAQ
+If you want to inforce passing a label to every class defined in your codebase, you can set `autofillLabels` to `false` at the start of app:
 
-- **Dev Extension Errors:** Add labels or enable autofillLabels.
-- **Anonymous Class Errors:** Export untyped bases.
-- **Selective Labeling:** Use `autofillLabels: true` or empty `@WithSigil()` for auto-generation.
+```ts
+import { updateSigilOptions } from '@vicin/sigil';
+
+updateSigilOptions({ autofillLabels: false });
+```
+
+Now if you forgot to pass a label error is thrown.
 
 ---
 
-## Phantom
+## Which pattern should I use?
 
-`Phantom` is another lightweight TypeScript library I created for achieving **nominal typing** on primitives and objects through type-only metadata. It solves the problem of structural typing in TypeScript allowing accidental misuse of identical shapes (e.g., confusing `UserId` and `PostId` as both strings) by enabling compile-time distinctions with features like **brands**, **constrained identities**, **variants for states**, **additive traits**, and **reversible transformations**. This makes it ideal for domain-driven design (DDD) without runtime overhead.
+- Want simplest setup? → Extend `Sigil`
+- Want full nominal typing? → Use HOF pattern
+- Want clean class bodies? → Use HOF
+- Want fewer wrapper exports? → Use Decorators
 
-`Phantom` works seamlessly in conjunction with `Sigil`, use `Sigil` for nominal identity on classes (runtime-safe checks across bundles), and `Phantom` for primitives/objects. Together, they provide **end-to-end type safety**: e.g., a Sigil-branded `User` class could hold a Phantom-branded `UserId` string property, enforcing domain boundaries at both compile and runtime.
+---
+
+## Troubleshooting & FAQ
 
-- **GitHub: [@phantom](https://github.com/ZiadTaha62/phantom)**
-- **NPM: [@phantom](https://www.npmjs.com/package/@vicin/phantom)**
+- **Dev Extension Errors:** Add labels or enable autofillLabels.
+- **Anonymous Class Errors:** Export untyped bases.
+- **Selective Labeling:** Use `autofillLabels: true` or empty `@WithSigil()` for auto-generation.
 
 ---
 

package/dist/index.d.mts

@@ -3,7 +3,7 @@
  * ----------------------------------------- */
 /**
  * Static-side interface describing methods and properties added to a class
- * constructor when it is sigilized.
+ * constructor when it is sigilified.
  *
  * The properties and methods described here mirror the getters and static
  * predicates implemented by the `Sigilify` mixin.
@@ -22,8 +22,10 @@ interface ISigilStatic<L extends string = string, P extends Function = never> {
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
     } & SigilBrandOf<P>>;
-    /** Class-level label constant (human readable). */
+    /** Class-level label constant (identity). */
     readonly SigilLabel: string;
+    /** Class-level label constant (human readable). */
+    readonly SigilEffectiveLabel: string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      * Useful for debugging and strict lineage comparisons.
@@ -91,8 +93,10 @@ interface ISigilInstance<L extends string = string, P extends Function = never>
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
     } & SigilBrandOf<P>>;
-    /** Returns human-readable sigil label of the class constructor. */
+    /** Returns identity sigil label of the class constructor. */
     getSigilLabel(): string;
+    /** Returns human-readable sigil label of the class constructor. */
+    getSigilEffectiveLabel(): string;
     /** Returns copy of sigil type label lineage of the class constructor. */
     getSigilLabelLineage(): readonly string[];
     /** Returns copy of sigil type label set of the class constructor. */
@@ -228,6 +232,7 @@ declare const Sigil: {
         isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
         isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
         getSigilLabel(): string;
+        getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
     };
@@ -235,6 +240,7 @@ declare const Sigil: {
         Sigil: true;
     };
     get SigilLabel(): string;
+    get SigilEffectiveLabel(): string;
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
@@ -260,6 +266,7 @@ declare const SigilError: {
         isOfType<T>(this: T, other: unknown): other is GetInstance<T>;
         isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
         getSigilLabel(): string;
+        getSigilEffectiveLabel(): string;
         getSigilLabelLineage(): readonly string[];
         getSigilLabelSet(): Readonly<Set<string>>;
     };
@@ -268,6 +275,7 @@ declare const SigilError: {
         SigilError: true;
     };
     get SigilLabel(): string;
+    get SigilEffectiveLabel(): string;
     get SigilLabelLineage(): readonly string[];
     get SigilLabelSet(): Readonly<Set<string>>;
     isSigilified(obj: unknown): obj is ISigil;
@@ -322,7 +330,7 @@ interface SigilOptions {
  *
  * @param opts - Partial options to merge into the global `OPTIONS` object.
  */
-declare const updateOptions: (opts: SigilOptions) => void;
+declare const updateSigilOptions: (opts: SigilOptions) => void;
 /** -----------------------------------------
  *  Label validation
  * ----------------------------------------- */
@@ -338,21 +346,10 @@ declare const DEFAULT_LABEL_REGEX: RegExp;
 /**
  * Class decorator factory that attaches sigil statics to a class constructor.
  *
- * Usage:
- * ```ts
- * @WithSigil('@myorg/mypkg.MyClass')
- * class MyClass { ... }
- * ```
- *
- * The returned decorator:
- * - validates the provided label (via `verifyLabel`)
- * - performs inheritance checks (via `checkInheritance`) in DEV builds
- * - attaches sigil-related statics to the constructor (via `decorateCtor`)
- *
  * Notes:
  * - This decorator is intended to be applied to classes only. When used
  *   incorrectly (e.g. on a property), it is a no-op.
- * - Throws an error during class creation if the label validation fails.
+ * - Throws an error during class creation if the label validation fails (in development only).
  *
  * @typeParam L - Narrow string literal type for the provided label.
  * @param label - Optional sigil label to assign to the decorated class (e.g. `@scope/pkg.ClassName`).
@@ -366,13 +363,6 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
  * Alternative to '@WithSigil' if you prefer HOFs.
  *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
- *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
  * @param Class - The constructor (class) to enhance.
@@ -382,15 +372,7 @@ declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (v
  */
 declare function withSigil<S extends Function, L extends string = string>(Class: S, label?: L, opts?: SigilOptions): S;
 /**
- * Convenience helper that combine 'withSigil' and 'typeSigil'.
- *
- * This does both:
- *  - validate (and autofill) a label,
- *  - perform runtime decoration (via `decorateCtor`),
- *  - return the constructor typed as `TypedSigil`.
- *
- * The helper is idempotent: `decorateCtor` will register the label and throw if already
- * decorated; we handle this gracefully in DEV to support HMR flows.
+ * Convenience helper that combine 'withSigil' and update 'SigilBrand'.
  *
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to attach.
@@ -405,9 +387,6 @@ declare function withSigilTyped<S extends Function, L extends string = string>(C
 /**
  * Runtime predicate that checks whether the provided value is a sigil constructor.
  *
- * This is a lightweight check that verifies the presence of an internal
- * symbol attached to the constructor.
- *
  * @param ctor - Constructor to test.
  * @returns `true` if `value` is a sigil constructor, otherwise `false`.
  */
@@ -423,8 +402,6 @@ declare function isSigilInstance(inst: unknown): inst is GetInstance<ISigil>;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
- * Uses `Object.hasOwn` to ensure we only check own properties.
- *
  * @param ctor - Constructor to check.
  * @returns `true` if `ctor` is a sigil base constructor.
  */
@@ -432,8 +409,6 @@ declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
 /**
  * Check whether the provided object is an instance of a sigil base constructor.
  *
- * This resolves the instance's constructor and delegates to `isSigilBaseCtor`.
- *
  * @param inst - The instance to test.
  * @returns `true` if `inst` is an instance of a sigil base constructor.
  */
@@ -441,8 +416,6 @@ declare function isSigilBaseInstance(inst: unknown): inst is GetInstance<ISigil>
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
- * This is an own-property check and does not traverse the prototype chain.
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if the constructor is explicitly decorated.
@@ -451,8 +424,6 @@ declare function isDecorated(ctor: Function): boolean;
 /**
  * Returns whether inheritance checks have already been performed for the constructor.
  *
- * This is used to avoid repeated checks during development (DEV-only checks).
- *
  * @internal
  * @param ctor - Constructor to test.
  * @returns `true` if inheritance checks were marked as completed.
@@ -460,19 +431,14 @@ declare function isDecorated(ctor: Function): boolean;
 declare function isInheritanceChecked(ctor: Function): boolean;
 
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
  *                If not passed a random label is generated instead.
  * @param opts - Options object to override any global options if needed.
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilized.
+ * @throws Error if `Base` is already sigilified.
  */
 declare function Sigilify<B extends Constructor, L extends string>(Base: B, label?: L, opts?: SigilOptions): {
     new (...args: any[]): {
@@ -509,11 +475,17 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
          */
         isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
         /**
-         * Returns the human-readable sigil label of this instance's constructor.
+         * Returns the identity sigil label of this instance's constructor.
          *
-         * @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
+         * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h') or '@Sigil.unknown' if constructor is missing.
          */
         getSigilLabel(): string;
+        /**
+         * Returns the human-readable sigil label of this instance's constructor.
+         *
+         * @returns The last passed label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' if constructor is missing.
+         */
+        getSigilEffectiveLabel(): string;
         /**
          * Returns a copy of the sigil type label lineage for this instance's constructor.
          *
@@ -538,9 +510,13 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
         Sigil: true;
     } & { [K in L]: true; }>;
     /**
-     * Class-level human-readable label constant for this sigil constructor.
+     * Class-level identity label constant for this sigil constructor.
      */
     get SigilLabel(): string;
+    /**
+     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
+     */
+    get SigilEffectiveLabel(): string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -587,19 +563,14 @@ declare function Sigilify<B extends Constructor, L extends string>(Base: B, labe
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 } & B;
 /**
- * Mixin factory that augments an existing class with Sigil runtime metadata and
- * helpers. Accept and return 'abstract' class.
- *
- * The returned class:
- * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
- * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ * Mixin factory that augments an existing class with Sigil runtime metadata and helpers. Accept and return 'abstract' class.
  *
  * @param Base - The base constructor to extend.
  * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
  *                If not passed a random label is generated instead.
  * @param opts - Options object to override any global options if needed.
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
- * @throws Error if `Base` is already sigilized.
+ * @throws Error if `Base` is already sigilified.
  */
 declare function SigilifyAbstract<B extends ConstructorAbstract, L extends string>(Base: B, label?: L, opts?: SigilOptions): ((abstract new (...args: any[]) => {
     /**
@@ -635,11 +606,17 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
      */
     isOfTypeStrict<T_1>(this: T_1, other: unknown): other is GetInstance<T_1>;
     /**
-     * Returns the human-readable sigil label of this instance's constructor.
+     * Returns the identity sigil label of this instance's constructor.
      *
-     * @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
+     * @returns The label string if passed (e.g. '@scope/pkg.ClassName'), random label if not passed (e.g. '@Sigil.auto-dq62ib6jnvmmlfbjhxh2937h') or '@Sigil.unknown' if constructor is missing.
      */
     getSigilLabel(): string;
+    /**
+     * Returns the human-readable sigil label of this instance's constructor.
+     *
+     * @returns The last passed label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' if constructor is missing.
+     */
+    getSigilEffectiveLabel(): string;
     /**
      * Returns a copy of the sigil type label lineage for this instance's constructor.
      *
@@ -664,9 +641,13 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
         Sigil: true;
     } & { [K in L]: true; }>;
     /**
-     * Class-level human-readable label constant for this sigil constructor.
+     * Class-level identity label constant for this sigil constructor.
      */
     get SigilLabel(): string;
+    /**
+     * Class-level human-readable label constant for this sigil constructor, last passed label in 'Sigil' chain by developer.
+     */
+    get SigilEffectiveLabel(): string;
     /**
      * Copy of the linearized sigil type label chain for the current constructor.
      *
@@ -721,4 +702,4 @@ declare function SigilifyAbstract<B extends ConstructorAbstract, L extends strin
     isOfTypeStrict<T>(this: T, other: unknown): other is GetInstance<T>;
 }) & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, Sigil, type SigilBrandOf, SigilError, type SigilOptions, Sigilify, SigilifyAbstract, type TypedSigil, type UpdateSigilBrand, WithSigil, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, updateSigilOptions, withSigil, withSigilTyped };