@adaas/a-concept 0.3.5 → 0.3.7

package/benchmarks/helpers.ts

@@ -0,0 +1,97 @@
+import Benchmark from 'benchmark';
+import Table from 'cli-table3';
+
+/**
+ * Result object collected after each benchmark completes
+ */
+export interface BenchResult {
+    name: string;
+    opsPerSec: string;
+    meanMs: string;
+    rme: string;
+    samples: number;
+}
+
+/**
+ * Creates and runs a Benchmark.js suite with formatted table output.
+ *
+ * @param suiteName  — Human-readable group name (printed as header)
+ * @param addBenchmarks — callback that receives `suite.add(...)` bound method
+ * @returns Promise that resolves with collected results
+ */
+export function createSuite(
+    suiteName: string,
+    addBenchmarks: (suite: Benchmark.Suite) => void
+): Promise<BenchResult[]> {
+    return new Promise((resolve) => {
+        const suite = new Benchmark.Suite(suiteName);
+        const results: BenchResult[] = [];
+
+        addBenchmarks(suite);
+
+        suite
+            .on('cycle', (event: Benchmark.Event) => {
+                const bench = event.target as any;
+                results.push({
+                    name: bench.name,
+                    opsPerSec: bench.hz.toFixed(2),
+                    meanMs: (bench.stats.mean * 1000).toFixed(4),
+                    rme: bench.stats.rme.toFixed(2),
+                    samples: bench.stats.sample.length,
+                });
+            })
+            .on('complete', () => {
+                printTable(suiteName, results);
+                resolve(results);
+            })
+            .run({ async: false });
+    });
+}
+
+/**
+ * Prints a formatted table of benchmark results to stdout
+ */
+export function printTable(title: string, results: BenchResult[]) {
+    console.log(`\n${'═'.repeat(70)}`);
+    console.log(`  📊  ${title}`);
+    console.log(`${'═'.repeat(70)}`);
+
+    const table = new Table({
+        head: ['Benchmark', 'ops/sec', 'mean (ms)', '± %', 'samples'],
+        colWidths: [40, 14, 14, 10, 10],
+        style: {
+            head: ['cyan'],
+        },
+    });
+
+    for (const r of results) {
+        table.push([r.name, r.opsPerSec, r.meanMs, `±${r.rme}%`, r.samples]);
+    }
+
+    console.log(table.toString());
+}
+
+/**
+ * Prints a summary comparison table across all suites
+ */
+export function printSummary(allResults: Map<string, BenchResult[]>) {
+    console.log(`\n${'═'.repeat(70)}`);
+    console.log(`  📋  PERFORMANCE SUMMARY`);
+    console.log(`${'═'.repeat(70)}`);
+
+    const table = new Table({
+        head: ['Suite', 'Benchmark', 'ops/sec', 'mean (ms)'],
+        colWidths: [25, 35, 14, 14],
+        style: {
+            head: ['green'],
+        },
+    });
+
+    for (const [suite, results] of allResults) {
+        for (const r of results) {
+            table.push([suite, r.name, r.opsPerSec, r.meanMs]);
+        }
+    }
+
+    console.log(table.toString());
+}

package/benchmarks/run-all.ts

@@ -0,0 +1,58 @@
+/**
+ * ============================================================
+ *  A-Concept Performance Benchmark Runner
+ * ============================================================
+ *
+ * Runs all benchmark suites and outputs a consolidated summary.
+ *
+ * Usage:
+ *   npx ts-node -r tsconfig-paths/register benchmarks/run-all.ts
+ *   npm run bench
+ */
+import { BenchResult, printSummary } from './helpers';
+import { runStepManagerBenchmarks } from './step-manager.bench';
+import { runFeatureTemplateBenchmarks } from './feature-template.bench';
+import { runScopeResolveBenchmarks } from './scope-resolve.bench';
+import { runFeatureLifecycleBenchmarks } from './feature-lifecycle.bench';
+
+
+async function main() {
+    console.log('\n🚀 Starting A-Concept Performance Benchmarks...\n');
+    console.log(`   Node.js ${process.version}`);
+    console.log(`   Date: ${new Date().toISOString()}`);
+    console.log(`   Platform: ${process.platform} ${process.arch}`);
+    console.log('');
+
+    const allSuites = new Map<string, BenchResult[]>();
+
+    // 1) StepManager benchmarks
+    console.log('\n📦 [1/4] A_StepsManager benchmarks...');
+    const smResults = await runStepManagerBenchmarks();
+    allSuites.set('StepManager', smResults);
+
+    // 2) Feature Template benchmarks
+    console.log('\n📦 [2/4] A_Context.featureTemplate benchmarks...');
+    const ftResults = await runFeatureTemplateBenchmarks();
+    allSuites.set('FeatureTemplate', ftResults);
+
+    // 3) Scope Resolve benchmarks
+    console.log('\n📦 [3/4] A_Scope resolve benchmarks...');
+    const srResults = await runScopeResolveBenchmarks();
+    allSuites.set('ScopeResolve', srResults);
+
+    // 4) Feature Lifecycle benchmarks
+    console.log('\n📦 [4/4] A_Feature lifecycle benchmarks...');
+    const flResults = await runFeatureLifecycleBenchmarks();
+    allSuites.set('FeatureLifecycle', flResults);
+
+    // Consolidated summary
+    printSummary(allSuites);
+
+    console.log('\n✅ All benchmarks completed.\n');
+}
+
+
+main().catch((err) => {
+    console.error('❌ Benchmark runner failed:', err);
+    process.exit(1);
+});

package/benchmarks/scope-resolve.bench.ts

@@ -0,0 +1,245 @@
+/**
+ * ============================================================
+ *  A_Scope Resolve Operations Performance Benchmarks
+ * ============================================================
+ *
+ * Measures:
+ *  - resolve() — single instance resolution (with parent chain traversal)
+ *  - resolveConstructor() — constructor lookup by name or type
+ *  - resolveAll() — batch resolution across scope hierarchy
+ *  - resolveDependency() — full dependency pipeline (filters, pagination)
+ *  - has() — existence checking with inheritance
+ *  - register() — registration performance
+ */
+import { A_Component } from "@adaas/a-concept/a-component";
+import { A_Entity } from "@adaas/a-concept/a-entity";
+import { A_Fragment } from "@adaas/a-concept/a-fragment";
+import { A_Scope } from "@adaas/a-concept/a-scope";
+import { A_Dependency } from "@adaas/a-concept/a-dependency";
+import { createSuite, BenchResult } from './helpers';
+
+
+// ──────────────────────────────────────────────────────────────
+// Fixture Classes
+// ──────────────────────────────────────────────────────────────
+
+class ComponentA extends A_Component { }
+class ComponentB extends A_Component { }
+class ComponentC extends A_Component { }
+class ComponentD extends A_Component { }
+class ComponentE extends A_Component { }
+
+class BaseComponent extends A_Component { }
+class DerivedComponent_A extends BaseComponent { }
+class DerivedComponent_B extends BaseComponent { }
+class DerivedComponent_C extends DerivedComponent_A { }
+
+class TestEntity extends A_Entity<{ foo: string }> {
+    public foo: string = 'default';
+
+    fromNew(params: { foo: string }) {
+        this.aseid = this.generateASEID();
+        this.foo = params.foo;
+    }
+}
+
+class TestFragment extends A_Fragment { }
+
+
+// ──────────────────────────────────────────────────────────────
+// Benchmark Suites
+// ──────────────────────────────────────────────────────────────
+
+export async function runScopeResolveBenchmarks(): Promise<BenchResult[]> {
+    const allResults: BenchResult[] = [];
+
+    // Suite 1: resolve() — single instance
+    const resolveResults = await createSuite('A_Scope.resolve — Single Instance', (suite) => {
+        // Flat scope
+        const flatScope = new A_Scope({
+            name: 'FlatScope',
+            components: [ComponentA, ComponentB, ComponentC, ComponentD, ComponentE]
+        });
+
+        // Nested scopes (3 levels)
+        const grandParent = new A_Scope({ name: 'GrandParent', components: [ComponentA] });
+        const parent = new A_Scope({ name: 'Parent', components: [ComponentB] });
+        const child = new A_Scope({ name: 'Child', components: [ComponentC] });
+        child.inherit(parent);
+        parent.inherit(grandParent);
+
+        suite
+            .add('resolve (flat, first component)', () => {
+                flatScope.resolve(ComponentA);
+            })
+            .add('resolve (flat, last component)', () => {
+                flatScope.resolve(ComponentE);
+            })
+            .add('resolve (nested, found in current)', () => {
+                child.resolve(ComponentC);
+            })
+            .add('resolve (nested, found in parent)', () => {
+                child.resolve(ComponentB);
+            })
+            .add('resolve (nested, found in grandparent)', () => {
+                child.resolve(ComponentA);
+            })
+            .add('resolve (not found)', () => {
+                flatScope.resolve(DerivedComponent_C);
+            });
+    });
+    allResults.push(...resolveResults);
+
+    // Suite 2: resolveConstructor()
+    const constructorResults = await createSuite('A_Scope.resolveConstructor', (suite) => {
+        const scope = new A_Scope({
+            name: 'ConstructorScope',
+            components: [ComponentA, DerivedComponent_A, DerivedComponent_B]
+        });
+
+        suite
+            .add('resolveConstructor (by class ref)', () => {
+                scope.resolveConstructor(ComponentA);
+            })
+            .add('resolveConstructor (by PascalCase name)', () => {
+                scope.resolveConstructor<ComponentA>('ComponentA');
+            })
+            .add('resolveConstructor (inherited class)', () => {
+                scope.resolveConstructor(BaseComponent);
+            })
+            .add('resolveConstructor (not found)', () => {
+                scope.resolveConstructor<ComponentE>('ComponentE');
+            });
+    });
+    allResults.push(...constructorResults);
+
+    // Suite 3: has() — existence checks
+    const hasResults = await createSuite('A_Scope.has — Existence Check', (suite) => {
+        const parentScope = new A_Scope({
+            name: 'ParentScope',
+            components: [ComponentA, ComponentB]
+        });
+        const childScope = new A_Scope({
+            name: 'ChildScope',
+            components: [ComponentC, ComponentD]
+        });
+        childScope.inherit(parentScope);
+
+        suite
+            .add('has (found in current scope)', () => {
+                childScope.has(ComponentC);
+            })
+            .add('has (found in parent scope)', () => {
+                childScope.has(ComponentA);
+            })
+            .add('has (not found anywhere)', () => {
+                childScope.has(ComponentE);
+            })
+            .add('has (by inheritance)', () => {
+                const scope = new A_Scope({
+                    name: 'InheritScope',
+                    components: [DerivedComponent_A]
+                });
+                scope.has(BaseComponent);
+            });
+    });
+    allResults.push(...hasResults);
+
+    // Suite 4: resolveAll() — batch resolution
+    const resolveAllResults = await createSuite('A_Scope.resolveAll — Batch Resolution', (suite) => {
+        const scope = new A_Scope({
+            name: 'BatchScope',
+            components: [DerivedComponent_A, DerivedComponent_B, DerivedComponent_C, ComponentE]
+        });
+
+        // Scope with entities
+        const entityScope = new A_Scope({ name: 'EntityScope' });
+        entityScope.register(TestEntity);
+        for (let i = 0; i < 20; i++) {
+            entityScope.register(new TestEntity({ foo: `val${i}` }));
+        }
+
+        // Nested scopes for resolveAll
+        const parentBatch = new A_Scope({
+            name: 'ParentBatch',
+            components: [DerivedComponent_A]
+        });
+        const childBatch = new A_Scope({
+            name: 'ChildBatch',
+            components: [DerivedComponent_B, DerivedComponent_C]
+        });
+        childBatch.inherit(parentBatch);
+
+        suite
+            .add('resolveAll (4 components, base class)', () => {
+                scope.resolveAll(BaseComponent);
+            })
+            .add('resolveAll (20 entities)', () => {
+                entityScope.resolveAll(TestEntity);
+            })
+            .add('resolveAll (nested scope)', () => {
+                childBatch.resolveAll(BaseComponent);
+            });
+    });
+    allResults.push(...resolveAllResults);
+
+    // Suite 5: resolveDependency() — full pipeline
+    const depResults = await createSuite('A_Scope.resolveDependency — Full Pipeline', (suite) => {
+        const scope = new A_Scope({
+            name: 'DepScope',
+            components: [ComponentA, ComponentB, ComponentC]
+        });
+
+        const entityScope = new A_Scope({ name: 'EntityDepScope' });
+        entityScope.register(TestEntity);
+        for (let i = 0; i < 10; i++) {
+            entityScope.register(new TestEntity({ foo: i < 5 ? 'bar' : 'baz' }));
+        }
+
+        const simpleDep = new A_Dependency(ComponentA);
+        const queryDep = new A_Dependency(TestEntity, { query: { foo: 'baz' } });
+        const paginatedDep = new A_Dependency(TestEntity, { pagination: { count: 5 } });
+
+        suite
+            .add('resolveDependency (simple)', () => {
+                scope.resolveDependency(simpleDep);
+            })
+            .add('resolveDependency (with query)', () => {
+                entityScope.resolveDependency(queryDep);
+            })
+            .add('resolveDependency (with pagination)', () => {
+                entityScope.resolveDependency(paginatedDep);
+            });
+    });
+    allResults.push(...depResults);
+
+    // Suite 6: register() performance
+    const registerResults = await createSuite('A_Scope.register — Registration', (suite) => {
+        suite
+            .add('register component (class)', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(ComponentA);
+            })
+            .add('register entity (instance)', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(new TestEntity({ foo: 'test' }));
+            })
+            .add('register 5 components', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(ComponentA);
+                scope.register(ComponentB);
+                scope.register(ComponentC);
+                scope.register(ComponentD);
+                scope.register(ComponentE);
+            });
+    });
+    allResults.push(...registerResults);
+
+    return allResults;
+}
+
+
+// Run standalone
+if (require.main === module) {
+    runScopeResolveBenchmarks().catch(console.error);
+}

package/benchmarks/step-manager.bench.ts

@@ -0,0 +1,146 @@
+/**
+ * ============================================================
+ *  A_StepsManager Performance Benchmarks
+ * ============================================================
+ * 
+ * Measures:
+ *  - Constructor + unique ID assignment
+ *  - Graph building + topological sort (toSortedArray)
+ *  - Full pipeline: steps → stages (toStages)
+ *  - Scaling behavior with increasing step counts
+ */
+import { A_Component } from "@adaas/a-concept/a-component";
+import { A_Dependency } from "@adaas/a-concept/a-dependency";
+import { A_StepsManager } from "@adaas/a-concept/a-step-manager";
+import { A_Feature } from "@adaas/a-concept/a-feature";
+import { A_Scope } from "@adaas/a-concept/a-scope";
+import { createSuite, BenchResult } from './helpers';
+
+
+// ──────────────────────────────────────────────────────────────
+// Fixture Helpers
+// ──────────────────────────────────────────────────────────────
+
+class BenchComponent extends A_Component {
+    async step1() { }
+    async step2() { }
+    async step3() { }
+    async step4() { }
+    async step5() { }
+    async step6() { }
+    async step7() { }
+    async step8() { }
+    async step9() { }
+    async step10() { }
+}
+
+function makeSteps(count: number, opts: { withDeps?: boolean } = {}) {
+    const steps: any[] = [];
+    for (let i = 0; i < count; i++) {
+        const step: any = {
+            name: `step${i}`,
+            dependency: new A_Dependency(BenchComponent),
+            handler: `step${i}`,
+        };
+        if (opts.withDeps && i > 0) {
+            step.after = `BenchComponent.step${i - 1}`;
+        }
+        steps.push(step);
+    }
+    return steps;
+}
+
+
+// ──────────────────────────────────────────────────────────────
+// Benchmark Suites
+// ──────────────────────────────────────────────────────────────
+
+export async function runStepManagerBenchmarks(): Promise<BenchResult[]> {
+    const allResults: BenchResult[] = [];
+
+    // Suite 1: Constructor performance
+    const constructorResults = await createSuite('A_StepsManager — Constructor', (suite) => {
+        const steps6 = makeSteps(6);
+        const steps20 = makeSteps(20);
+        const steps50 = makeSteps(50);
+
+        suite
+            .add('new A_StepsManager(6 steps)', () => {
+                new A_StepsManager(steps6);
+            })
+            .add('new A_StepsManager(20 steps)', () => {
+                new A_StepsManager(steps20);
+            })
+            .add('new A_StepsManager(50 steps)', () => {
+                new A_StepsManager(steps50);
+            });
+    });
+    allResults.push(...constructorResults);
+
+    // Suite 2: Topological sort
+    const sortResults = await createSuite('A_StepsManager — toSortedArray', (suite) => {
+        const steps6 = makeSteps(6);
+        const steps6Deps = makeSteps(6, { withDeps: true });
+        const steps20 = makeSteps(20);
+        const steps20Deps = makeSteps(20, { withDeps: true });
+        const steps50 = makeSteps(50);
+
+        suite
+            .add('toSortedArray (6 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps6);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (6 steps, chained)', () => {
+                const sm = new A_StepsManager(steps6Deps);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (20 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps20);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (20 steps, chained)', () => {
+                const sm = new A_StepsManager(steps20Deps);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (50 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps50);
+                sm.toSortedArray();
+            });
+    });
+    allResults.push(...sortResults);
+
+    // Suite 3: toStages (full pipeline)
+    const stagesResults = await createSuite('A_StepsManager — toStages', (suite) => {
+        const scope = new A_Scope({ name: 'BenchScope', components: [BenchComponent] });
+        const steps6 = makeSteps(6);
+        const steps20 = makeSteps(20);
+
+        suite
+            .add('toStages (6 steps)', () => {
+                const component = scope.resolve(BenchComponent)!;
+                const feature = new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: steps6,
+                });
+                // toStages is called internally during construction
+            })
+            .add('toStages (20 steps)', () => {
+                const component = scope.resolve(BenchComponent)!;
+                const feature = new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: steps20,
+                });
+            });
+    });
+    allResults.push(...stagesResults);
+
+    return allResults;
+}
+
+
+// Run standalone
+if (require.main === module) {
+    runStepManagerBenchmarks().catch(console.error);
+}

package/dist/browser/index.d.mts

@@ -783,6 +783,11 @@ declare class A_Meta<_StorageItems extends Record<any, any> = any, _SerializedTy
      * @param key
      * @returns
      */
+    /**
+     * Cache for compiled RegExp instances keyed by their string source.
+     * Avoids re-compiling the same regex pattern on every find() call.
+     */
+    private _regExpCache?;
     private convertToRegExp;
     /**
      * Method to find values in the map by name.
@@ -1487,8 +1492,10 @@ type A_TYPES__FeatureAvailableComponents = InstanceType<A_TYPES__FeatureAvailabl
 type A_TYPES__FeatureAvailableConstructors = A_TYPES__Component_Constructor | A_TYPES__Entity_Constructor | A_TYPES__Container_Constructor;
 /**
  * Indicates a type of Feature Define decorator
+ *
+ * [!] Uses a single generic descriptor to support both sync and async methods
  */
-type A_TYPES__FeatureDefineDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>;
+type A_TYPES__FeatureDefineDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any>;
 /**
  * Describes additional configuration properties to be used in Feature Define decorator
  */
@@ -1549,8 +1556,10 @@ type A_TYPES__FeatureDefineDecoratorMeta = {
 };
 /**
  * Descriptor type for A_Extend decorator
+ *
+ * [!] Uses a single generic descriptor to support both sync and async methods
  */
-type A_TYPES__FeatureExtendDecoratorDescriptor = TypedPropertyDescriptor<() => any> | TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>> | TypedPropertyDescriptor<() => Promise<any>>;
+type A_TYPES__FeatureExtendDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any>;
 /**
  * Target type for A_Extend decorator
  *
@@ -2978,6 +2987,15 @@ type A_TYPES_ScopeDependentComponents = A_Component | A_Entity | A_Fragment | A_
 type A_TYPES_ScopeIndependentComponents = A_Error | A_Scope | A_Caller;
 
 declare class A_Scope<_MetaItems extends Record<string, any> = any, _ComponentType extends A_TYPES__Component_Constructor[] = A_TYPES__Component_Constructor[], _ErrorType extends A_TYPES__Error_Constructor[] = A_TYPES__Error_Constructor[], _EntityType extends A_TYPES__Entity_Constructor[] = A_TYPES__Entity_Constructor[], _FragmentType extends A_Fragment[] = A_Fragment[]> {
+    /**
+     * Auto-incrementing counter for generating unique scope IDs.
+     */
+    private static _nextUid;
+    /**
+     * Unique numeric ID for this scope instance. Used as a cache key discriminator
+     * to prevent collisions between scopes with the same name or version.
+     */
+    readonly uid: number;
     /**
      * Scope Name uses for identification and logging purposes
      */
@@ -2992,6 +3010,20 @@ declare class A_Scope<_MetaItems extends Record<string, any> = any, _ComponentTy
      * throughout the execution pipeline or within running containers.
      */
     protected _meta: A_Meta<_MetaItems>;
+    /**
+     * Monotonically increasing version counter. Incremented on every mutation
+     * (register, deregister, import, deimport, inherit, destroy) so that
+     * external caches (e.g. A_Context feature-extension cache) can detect
+     * staleness cheaply via numeric comparison.
+     */
+    protected _version: number;
+    /**
+     * Cache for resolveConstructor results (both positive and negative).
+     * Key = constructor name (string) or constructor reference toString.
+     * Value = resolved constructor or `null` for negative results.
+     * Invalidated by incrementing _version (cache is cleared on bump).
+     */
+    protected _resolveConstructorCache: Map<string | Function, Function | null>;
     /**
      * A set of allowed components, A set of constructors that are allowed in the scope
      *
@@ -3053,6 +3085,11 @@ declare class A_Scope<_MetaItems extends Record<string, any> = any, _ComponentTy
      * Returns a list of Constructors for A-Errors that are available in the scope
      */
     get allowedErrors(): Set<_ErrorType[number]>;
+    /**
+     * Returns the current version of the scope. Each mutation increments the version,
+     * allowing external caches to detect staleness via numeric comparison.
+     */
+    get version(): number;
     /**
      * Returns an Array of entities registered in the scope
      *
@@ -3089,6 +3126,11 @@ declare class A_Scope<_MetaItems extends Record<string, any> = any, _ComponentTy
      * @returns
      */
     get parent(): A_Scope | undefined;
+    /**
+     * Increments the scope version and clears internal caches.
+     * Must be called on every scope mutation (register, deregister, import, deimport, inherit, destroy).
+     */
+    protected bumpVersion(): void;
     /**
      * A_Scope is a unique A-Concept Structure that allows to operate with A-Concept Primitives and Models in a specific context and with specific rules.
      *  It refers to the visibility and accessibility of :
@@ -3388,6 +3430,11 @@ declare class A_Scope<_MetaItems extends Record<string, any> = any, _ComponentTy
      */
     error: A_TYPES__Ctor<T>): A_TYPES__Error_Constructor<T> | undefined;
     resolveConstructor<T extends A_TYPES__A_DependencyInjectable>(name: string | A_TYPES__Ctor<T>): A_TYPES__Entity_Constructor<T> | A_TYPES__Component_Constructor<T> | A_TYPES__Fragment_Constructor<T> | undefined;
+    /**
+     * Internal uncached implementation of resolveConstructor for string names.
+     * Separated to allow the public method to wrap with caching.
+     */
+    private _resolveConstructorUncached;
     /**
      * This method should resolve all instances of the components, or entities within the scope, by provided parent class
      * So in case of providing a base class it should return all instances that extends this base class
@@ -4151,6 +4198,23 @@ declare class A_Context {
      * Meta provides to store extra information about the class behavior and configuration.
      */
     protected _metaStorage: Map<A_TYPES__MetaLinkedComponentConstructors, A_Meta>;
+    /**
+     * Monotonically increasing version counter for _metaStorage.
+     * Incremented whenever a new entry is added to _metaStorage so that
+     * caches depending on meta content can detect staleness.
+     */
+    protected _metaVersion: number;
+    /**
+     * Cache for featureExtensions results.
+     * Key format: `${featureName}::${componentConstructorName}::${scopeVersion}::${metaVersion}`
+     * Automatically invalidated when scope version or meta version changes.
+     */
+    protected _featureExtensionsCache: Map<string, Array<A_TYPES__A_StageStep>>;
+    /**
+     * Maximum number of entries in the featureExtensions cache.
+     * When exceeded, the entire cache is cleared to prevent unbounded growth.
+     */
+    protected static readonly FEATURE_EXTENSIONS_CACHE_MAX_SIZE = 1024;
     protected _globals: Map<string, any>;
     /**
      * Private constructor to enforce singleton pattern.
@@ -4408,6 +4472,10 @@ declare class A_Context {
     /**
      * method helps to filter steps in a way that only the most derived classes are kept.
      *
+     * Optimized: Uses a pre-built constructor→class map and single-pass prototype chain
+     * walk to eliminate parent classes in O(n·d) where d is inheritance depth,
+     * instead of the previous O(n²) with isPrototypeOf checks.
+     *
      * @param scope
      * @param items
      * @returns