@via-profit/ability 3.5.4 → 3.6.1

package/dist/index.js

@@ -1,25 +1,12 @@
 'use strict';
 
-class AbilityCode {
-    _code;
-    constructor(code) {
-        this._code = code;
-    }
-    get code() {
-        return this._code;
-    }
-    isEqual(compareWith) {
-        return compareWith !== null && this.code === compareWith.code;
-    }
-    isNotEqual(compareWith) {
-        return !this.isEqual(compareWith);
-    }
-}
-
-class AbilityCompare extends AbilityCode {
-    static and = new AbilityCompare('and');
-    static or = new AbilityCompare('or');
+function brand$4(code) {
+    return code;
 }
+const AbilityCompare = {
+    or: brand$4('or'),
+    and: brand$4('and'),
+};
 
 class AbilityError extends Error {
     constructor(message, options) {
@@ -40,111 +27,297 @@ class AbilityParserError extends Error {
     }
 }
 
-class AbilityCondition extends AbilityCode {
-    static equals;
-    static not_equals;
-    static greater_than;
-    static less_than;
-    static less_or_equal;
-    static greater_or_equal;
-    static in;
-    static not_in;
-    static contains;
-    static not_contains;
-    static length_greater_than;
-    static length_less_than;
-    static length_equals;
-    static always;
-    static never;
-    static {
-        this.equals = new AbilityCondition('=');
-        this.not_equals = new AbilityCondition('<>');
-        this.greater_than = new AbilityCondition('>');
-        this.less_than = new AbilityCondition('<');
-        this.less_or_equal = new AbilityCondition('<=');
-        this.greater_or_equal = new AbilityCondition('>=');
-        this.in = new AbilityCondition('in');
-        this.not_in = new AbilityCondition('not in');
-        this.contains = new AbilityCondition('contains');
-        this.not_contains = new AbilityCondition('not contains');
-        this.length_greater_than = new AbilityCondition('length greater than');
-        this.length_less_than = new AbilityCondition('length less than');
-        this.length_equals = new AbilityCondition('length equals');
-        this.always = new AbilityCondition('always');
-        this.never = new AbilityCondition('never');
-    }
-    static fromLiteral(literal) {
-        const map = {
-            equals: this.equals,
-            not_equals: this.not_equals,
-            greater_than: this.greater_than,
-            less_than: this.less_than,
-            less_or_equal: this.less_or_equal,
-            greater_or_equal: this.greater_or_equal,
-            in: this.in,
-            not_in: this.not_in,
-            contains: this.contains,
-            not_contains: this.not_contains,
-            length_greater_than: this.length_greater_than,
-            length_equals: this.length_equals,
-            always: this.always,
-            never: this.never,
-            length_less_than: this.length_less_than,
-        };
-        const condition = map[literal];
-        if (!condition) {
-            throw new AbilityParserError(`Literal "${literal}" does not found in AbilityCondition class`);
-        }
-        return condition;
+function brand$3(code) {
+    return code;
+}
+const AbilityCondition = {
+    equals: brand$3('='),
+    not_equals: brand$3('<>'),
+    greater_than: brand$3('>'),
+    less_than: brand$3('<'),
+    less_or_equal: brand$3('<='),
+    greater_or_equal: brand$3('>='),
+    in: brand$3('in'),
+    not_in: brand$3('not in'),
+    contains: brand$3('contains'),
+    not_contains: brand$3('not contains'),
+    length_greater_than: brand$3('length greater than'),
+    length_less_than: brand$3('length less than'),
+    length_equals: brand$3('length equals'),
+    always: brand$3('always'),
+    never: brand$3('never'),
+};
+function fromLiteral(literal) {
+    const map = {
+        equals: AbilityCondition.equals,
+        not_equals: AbilityCondition.not_equals,
+        greater_than: AbilityCondition.greater_than,
+        less_than: AbilityCondition.less_than,
+        less_or_equal: AbilityCondition.less_or_equal,
+        greater_or_equal: AbilityCondition.greater_or_equal,
+        in: AbilityCondition.in,
+        not_in: AbilityCondition.not_in,
+        contains: AbilityCondition.contains,
+        not_contains: AbilityCondition.not_contains,
+        length_greater_than: AbilityCondition.length_greater_than,
+        length_less_than: AbilityCondition.length_less_than,
+        length_equals: AbilityCondition.length_equals,
+        always: AbilityCondition.always,
+        never: AbilityCondition.never,
+    };
+    const value = map[literal];
+    if (!value) {
+        const expected = Object.keys(map).join(', ');
+        throw new AbilityParserError(`Literal "${literal}" does not found in AbilityCondition. Expected one of: ${expected}`);
     }
-    get literal() {
-        switch (this.code) {
-            case '=':
-                return 'equals';
-            case '<>':
-                return 'not_equals';
-            case '>':
-                return 'greater_than';
-            case '<':
-                return 'less_than';
-            case '>=':
-                return 'greater_or_equal';
-            case '<=':
-                return 'less_or_equal';
-            case 'in':
-                return 'in';
-            case 'not in':
-                return 'not_in';
-            case 'contains':
-                return 'contains';
-            case 'not contains':
-                return 'not_contains';
-            case 'length greater than':
-                return 'length_greater_than';
-            case 'length less than':
-                return 'length_less_than';
-            case 'length equals':
-                return 'length_equals';
-            case 'always':
-                return 'always';
-            case 'never':
-                return 'never';
-            default:
-                throw new Error(`Unknown condition code: ${String(this.code)}`);
+    return value;
+}
+function toLiteral(cond) {
+    switch (cond) {
+        case AbilityCondition.equals:
+            return 'equals';
+        case AbilityCondition.not_equals:
+            return 'not_equals';
+        case AbilityCondition.greater_than:
+            return 'greater_than';
+        case AbilityCondition.less_than:
+            return 'less_than';
+        case AbilityCondition.less_or_equal:
+            return 'less_or_equal';
+        case AbilityCondition.greater_or_equal:
+            return 'greater_or_equal';
+        case AbilityCondition.in:
+            return 'in';
+        case AbilityCondition.not_in:
+            return 'not_in';
+        case AbilityCondition.contains:
+            return 'contains';
+        case AbilityCondition.not_contains:
+            return 'not_contains';
+        case AbilityCondition.length_greater_than:
+            return 'length_greater_than';
+        case AbilityCondition.length_less_than:
+            return 'length_less_than';
+        case AbilityCondition.length_equals:
+            return 'length_equals';
+        case AbilityCondition.always:
+            return 'always';
+        case AbilityCondition.never:
+            return 'never';
+        default:
+            return 'never';
+    }
+}
+function isConditionEqual(a, b) {
+    return a !== null && b !== null && a === b;
+}
+function isConditionNotEqual(a, b) {
+    return !isConditionEqual(a, b);
+}
+
+function brand$2(code) {
+    return code;
+}
+const AbilityMatch = {
+    pending: brand$2('pending'),
+    match: brand$2('match'),
+    mismatch: brand$2('mismatch'),
+    exceptMismatch: brand$2('except-mismatch'),
+    disabled: brand$2('disabled'),
+};
+
+class AbilityExplain {
+    type;
+    children;
+    name;
+    match;
+    constructor(config, children = []) {
+        this.type = config.type;
+        this.children = children;
+        this.name = config.name;
+        this.match = config.match;
+    }
+    toString(indent = 0) {
+        const pad = ' '.repeat(indent);
+        const mark = this.match === AbilityMatch.match ? '✓' : '✗';
+        let out = '';
+        if (this.type === 'policy') {
+            out += '\n';
         }
+        out += `${pad}${mark} ${this.type} «${this.name}» is ${this.match}`;
+        this.children.forEach(child => {
+            out += '\n' + child.toString(indent + 1);
+        });
+        return out;
+    }
+}
+class AbilityExplainRule extends AbilityExplain {
+    constructor(rule) {
+        super({
+            type: 'rule',
+            match: rule.state,
+            name: rule.name,
+        });
+    }
+}
+class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet) {
+        const children = ruleSet.rules.map(rule => new AbilityExplainRule(rule));
+        super({
+            type: 'ruleSet',
+            match: ruleSet.state,
+            name: ruleSet.name,
+        }, children);
+    }
+}
+class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy) {
+        const children = policy.ruleSet.map(ruleSet => new AbilityExplainRuleSet(ruleSet));
+        super({
+            type: 'policy',
+            name: policy.priority > -1 ? `@priority ${policy.priority} ${policy.name}` : policy.name,
+            match: policy.matchState,
+        }, children);
+    }
+}
+
+class AbilityResult {
+    effect;
+    strategy;
+    constructor(effect, strategy) {
+        this.effect = effect;
+        this.strategy = strategy;
+    }
+    /**
+     * Returns a list of explanations for each policy involved in the ability evaluation.
+     * Each item describes how a specific policy contributed to the final permission result.
+     *
+     * Useful for debugging, logging, or building UI tools that visualize permission logic.
+     */
+    explain() {
+        return this.strategy.policies.map(policy => {
+            return new AbilityExplainPolicy(policy);
+        });
     }
+    isAllowed = () => {
+        return this.strategy.isAllowed();
+    };
+    isDenied = () => {
+        return this.strategy.isDenied();
+    };
 }
 
-class AbilityMatch extends AbilityCode {
-    static pending = new AbilityMatch('pending');
-    static match = new AbilityMatch('match');
-    static mismatch = new AbilityMatch('mismatch');
+class AbilityResolver {
+    StrategyClass;
+    policyEntries;
+    constructor(
+    /**
+     * `Important!` The incorrect Resources type was intentionally passed to AbilityPolicy so that TypeScript could suggest the name of the permission and the structure of its resource in the parse method.
+     */
+    policyOrListOfPolicies, strategy, options = {}) {
+        const policies = this.toArray(policyOrListOfPolicies);
+        const filtered = options.tags
+            ? policies.filter(p => p.tags.some(tag => options.tags.includes(tag)))
+            : policies;
+        const sorted = [...filtered].sort((a, b) => b.priority - a.priority);
+        this.policyEntries = sorted.map(policy => ({
+            policy,
+            normalizedPermission: AbilityResolver.normalizePermission(policy.permission),
+            segments: AbilityResolver.normalizePermission(policy.permission).split('.'),
+        }));
+        this.StrategyClass = strategy;
+    }
+    /**
+     * Resolve policy for the resource and permission key
+     *
+     * @param permission - Permission key
+     * @param resource - Resource
+     * @param environment
+     */
+    resolve(permission, resource, environment) {
+        const inputNormalized = AbilityResolver.normalizePermission(String(permission));
+        const inputSegments = inputNormalized.split('.');
+        const filteredPolicies = this.policyEntries
+            .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+            .map(entry => entry.policy);
+        // 2. check the policies
+        for (const policy of filteredPolicies) {
+            if (policy.disabled) {
+                continue;
+            }
+            const policyMatchState = policy.check(resource, environment);
+            if (policyMatchState === AbilityMatch.pending) {
+                throw new AbilityError(`The policy "${policy.name}" is still in a pending state. Make sure to call "check" to evaluate the policy before resolving permissions.`);
+            }
+        }
+        // 3. Use strategy
+        const strategy = new this.StrategyClass(filteredPolicies);
+        const effect = strategy.evaluate();
+        return new AbilityResult(effect, strategy);
+    }
+    enforce(permission, resource, environment) {
+        const result = this.resolve(permission, resource, environment);
+        if (result.isDenied()) {
+            throw new AbilityError(`Permission denied`);
+        }
+    }
+    /**
+     * @deprecated - will be removed
+     *
+     * Check if the permission key is contained in another permission key
+     * @param permissionA - The first permission to check
+     * @param permissionB - The second permission to check
+     */
+    static isInPermissionContain(permissionA, permissionB) {
+        const A = permissionA.split('.');
+        const B = permissionB.split('.');
+        const [longer, shorter] = A.length >= B.length ? [A, B] : [B, A];
+        return shorter.every((chunk, i) => {
+            return chunk === '*' || longer[i] === '*' || chunk === longer[i];
+        });
+    }
+    toArray(value) {
+        return [...(Array.isArray(value) ? value : [value])];
+    }
+    static normalizePermission(permission) {
+        return permission
+            .trim()
+            .replace(/^permission\./, '') // remove prefix
+            .replace(/\.+/g, '.') // collapse multiple dots
+            .toLowerCase(); // optional: make case-insensitive
+    }
+    static matchPermissions(policySegments, inputSegments) {
+        const maxLen = Math.max(policySegments.length, inputSegments.length);
+        for (let i = 0; i < maxLen; i++) {
+            const pSeg = policySegments[i];
+            const iSeg = inputSegments[i];
+            if (pSeg === undefined) {
+                return false;
+            }
+            if (pSeg === '*') {
+                continue; // '*'
+            }
+            if (iSeg === undefined) {
+                return false;
+            }
+            if (pSeg !== iSeg) {
+                return false;
+            }
+        }
+        return true;
+    }
 }
 
 class AbilityTypeGenerator {
     policies;
+    policyEntries;
     constructor(policies) {
         this.policies = policies;
+        this.policyEntries = policies.map(policy => ({
+            policy,
+            normalizedPermission: AbilityResolver.normalizePermission(policy.permission),
+            segments: AbilityResolver.normalizePermission(policy.permission).split('.'),
+        }));
     }
     /**
      * Generates TypeScript type definitions based on the provided policies.
@@ -152,43 +325,103 @@ class AbilityTypeGenerator {
      */
     generateTypeDefs() {
         // Structure to store types: { [action]: { [subjectPath]: type } }
-        const typeStructure = {};
+        const resorceStructure = {};
+        const environmentStructure = {};
+        // tags
+        const allTags = new Set();
         // Iterate through all policies
         this.policies.forEach(policy => {
+            policy.tags.forEach(tag => allTags.add(tag));
             const action = policy.permission;
             // Initialize object for action if it doesn't exist
-            if (!typeStructure[action]) {
-                typeStructure[action] = {};
+            if (!resorceStructure[action]) {
+                resorceStructure[action] = {};
             }
             // Iterate through all ruleSets in the policy
             policy.ruleSet.forEach(ruleSet => {
                 // Iterate through all rules in the ruleSet
                 ruleSet.rules.forEach(rule => {
                     const subjectPath = rule.subject;
-                    const existingType = typeStructure[action][subjectPath];
                     const ruleType = this.determineTypeFromRule(rule);
                     if (!ruleType) {
                         return;
                     }
-                    if (existingType && existingType !== ruleType) {
-                        // If a type already exists for this path, create a union
-                        typeStructure[action][subjectPath] = `${existingType} | ${ruleType}`;
+                    // -----------------------------
+                    // ENVIRONMENT HANDLING (subject)
+                    // -----------------------------
+                    if (subjectPath.startsWith('env.')) {
+                        const envPath = subjectPath.replace(/^env\./, '');
+                        if (!environmentStructure[action]) {
+                            environmentStructure[action] = {};
+                        }
+                        environmentStructure[action][envPath] = ruleType;
                     }
                     else {
-                        typeStructure[action][subjectPath] = ruleType;
+                        const existingType = resorceStructure[action][subjectPath];
+                        if (existingType && existingType !== ruleType) {
+                            resorceStructure[action][subjectPath] = `${existingType} | ${ruleType}`;
+                        }
+                        else {
+                            resorceStructure[action][subjectPath] = ruleType;
+                        }
+                    }
+                    // -----------------------------
+                    // RESOURCE PATH HANDLING (right side)
+                    // -----------------------------
+                    if (typeof rule.resource === 'string' && this.isPath(rule.resource)) {
+                        const resourcePath = rule.resource;
+                        // env.* справа
+                        if (resourcePath.startsWith('env.')) {
+                            const envPath = resourcePath.replace(/^env\./, '');
+                            if (!environmentStructure[action]) {
+                                environmentStructure[action] = {};
+                            }
+                            const existingEnvType = environmentStructure[action][envPath];
+                            const targetType = ruleType; // или 'unknown', если хочешь жёстко
+                            if (existingEnvType && existingEnvType !== targetType) {
+                                environmentStructure[action][envPath] = `${existingEnvType} | ${targetType}`;
+                            }
+                            else {
+                                environmentStructure[action][envPath] = targetType;
+                            }
+                        }
+                        else {
+                            // обычный ресурс справа
+                            if (!resorceStructure[action]) {
+                                resorceStructure[action] = {};
+                            }
+                            const existingResType = resorceStructure[action][resourcePath];
+                            const targetType = ruleType; // или 'unknown'
+                            if (existingResType && existingResType !== targetType) {
+                                resorceStructure[action][resourcePath] = `${existingResType} | ${targetType}`;
+                            }
+                            else {
+                                resorceStructure[action][resourcePath] = targetType;
+                            }
+                        }
                     }
                 });
             });
         });
         const filteredStructure = {};
-        Object.entries(typeStructure).forEach(([action, fields]) => {
+        Object.entries(resorceStructure).forEach(([action, fields]) => {
             if (!action.endsWith('.*')) {
                 filteredStructure[action] = fields;
             }
         });
         // Transform flat structure into nested structure for easier use
         const nestedStructure = this.buildNestedStructure(filteredStructure);
-        return this.formatTypeDefinitions(nestedStructure);
+        const nestedEnvironment = this.buildNestedStructure(environmentStructure);
+        return this.formatTypeDefinitions(nestedStructure, nestedEnvironment, allTags);
+    }
+    isPath(value) {
+        if (typeof value !== 'string') {
+            return false;
+        }
+        if (value.startsWith('"') || value.startsWith("'")) {
+            return false;
+        }
+        return value.includes('.');
     }
     /**
      * Determines TypeScript type based on the rule
@@ -196,25 +429,32 @@ class AbilityTypeGenerator {
      * @returns TypeScript type as string
      */
     determineTypeFromRule(rule) {
-        if (rule.condition.isEqual(AbilityCondition.never) ||
-            rule.condition.isEqual(AbilityCondition.always)) {
+        if (rule.condition === AbilityCondition.never || rule.condition === AbilityCondition.always) {
             return null;
         }
+        if (rule.condition === AbilityCondition.contains ||
+            rule.condition === AbilityCondition.not_contains) {
+            return this.getArrayType(rule.resource);
+        }
+        if (rule.condition === AbilityCondition.length_equals ||
+            rule.condition === AbilityCondition.length_greater_than ||
+            rule.condition === AbilityCondition.length_less_than) {
+            return 'string | readonly unknown[]';
+        }
         // Numeric comparisons - always number
-        if (rule.condition.isEqual(AbilityCondition.greater_than) ||
-            rule.condition.isEqual(AbilityCondition.less_than) ||
-            rule.condition.isEqual(AbilityCondition.greater_or_equal) ||
-            rule.condition.isEqual(AbilityCondition.less_or_equal)) {
+        if (rule.condition === AbilityCondition.greater_than ||
+            rule.condition === AbilityCondition.greater_or_equal ||
+            rule.condition === AbilityCondition.less_than ||
+            rule.condition === AbilityCondition.less_or_equal) {
             return 'number';
         }
         // Array operations
-        if (rule.condition.isEqual(AbilityCondition.in) ||
-            rule.condition.isEqual(AbilityCondition.not_in)) {
-            return this.getArrayType(rule.resource);
+        if (rule.condition === AbilityCondition.in || rule.condition === AbilityCondition.not_in) {
+            return this.getInArrayType(rule.resource);
         }
         // Equality/Inequality operations
-        if (rule.condition.isEqual(AbilityCondition.equals) ||
-            rule.condition.isEqual(AbilityCondition.not_equals)) {
+        if (rule.condition === AbilityCondition.equals ||
+            rule.condition === AbilityCondition.not_equals) {
             return this.getPrimitiveType(rule.resource);
         }
         return 'any';
@@ -225,20 +465,23 @@ class AbilityTypeGenerator {
      * @returns TypeScript array type as string
      */
     getArrayType(resource) {
+        const elementType = this.getInArrayType(resource);
+        return `readonly ${elementType}[]`;
+    }
+    getInArrayType(resource) {
         if (Array.isArray(resource)) {
             if (resource.length === 0) {
-                return 'any[]';
+                return 'unknown';
             }
             // Determine types of array elements
             const elementTypes = new Set(resource.map(item => this.getPrimitiveType(item)));
-            const elementType = elementTypes.size === 1
+            return elementTypes.size === 1
                 ? Array.from(elementTypes)[0]
                 : `(${Array.from(elementTypes).join(' | ')})`;
-            return `readonly ${elementType}[]`;
         }
         // If resource is not an array but condition is in/not_in,
         // it expects an array of such elements
-        return `readonly ${this.getPrimitiveType(resource)}[]`;
+        return this.getPrimitiveType(resource);
     }
     /**
      * Gets primitive TypeScript type for a value
@@ -247,11 +490,15 @@ class AbilityTypeGenerator {
      */
     getPrimitiveType(value) {
         if (value === null) {
-            return 'null';
+            return 'null | unknown';
         }
         if (value === undefined) {
             return 'undefined';
         }
+        if (typeof value === 'string' && this.isPath(value)) {
+            // This is not a string literal, but a path to another field.
+            return 'unknown';
+        }
         switch (typeof value) {
             case 'string':
                 return 'string';
@@ -304,28 +551,100 @@ class AbilityTypeGenerator {
     /**
      * Formats type structure into a string
      * @param structure - Nested type structure
+     * @param environment
+     * @param allTags
      * @returns Formatted TypeScript type definition string
      */
-    formatTypeDefinitions(structure) {
+    formatTypeDefinitions(structure, environment, allTags) {
         let output = '// Automatically generated by via-profit/ability\n';
         output += '// Do not edit manually\n';
         output += 'export type Resources = {\n';
         const sortedActions = Object.keys(structure).sort();
-        sortedActions.forEach(action => {
-            const actionObj = structure[action];
+        sortedActions.forEach(permission => {
+            const actionObj = structure[permission];
             const isEmpty = Object.keys(actionObj).length === 0;
+            const inputNormalized = AbilityResolver.normalizePermission(permission);
+            const inputSegments = inputNormalized.split('.');
+            const filteredPolicies = this.policyEntries
+                .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+                .map(entry => entry.policy);
+            // Effects
+            const effects = [...new Set(filteredPolicies.map(p => p.effect))].sort();
+            // Policies list
+            const items = filteredPolicies
+                .sort((a, b) => a.id.localeCompare(b.id))
+                .map(p => {
+                const effect = p.effect.padEnd(6, ' '); // permit / deny / audit
+                const displayName = p.name === p.id ? 'Unnamed policy' : p.name;
+                return `  *   - ${effect} ${p.id}  "${displayName}"`;
+            })
+                .join('\n');
+            //
+            output += `
+ /**
+  * Permission: ${permission}
+  * Effects: ${effects.join(', ')}
+  * Policies:
+${items}
+  */
+`;
             if (isEmpty) {
-                // Пустой объект → undefined
-                output += `  ['${action}']: undefined;\n`;
+                // empty object → undefined
+                output += `  ['${permission}']: undefined;\n`;
             }
             else {
-                // Непустой объект → как раньше
-                output += `  ['${action}']: {\n`;
+                // not empty object
+                output += `  ['${permission}']: {\n`;
                 output += this.formatNestedObject(actionObj, 4);
-                output += '  };\n';
+                output += '  } | null | undefined;\n';
             }
         });
         output += '}\n';
+        // tags
+        const tagsUnion = allTags.size > 0
+            ? Array.from(allTags)
+                .sort()
+                .map(tag => `'${tag}'`)
+                .join(' | ')
+            : 'never';
+        output += `\n\nexport type PolicyTags = ${tagsUnion};\n`;
+        // environments
+        output += '\n\nexport type Environment = {\n';
+        Object.entries(environment).forEach(([permission, envObj]) => {
+            const isEmpty = Object.keys(envObj).length === 0;
+            const inputNormalized = AbilityResolver.normalizePermission(permission);
+            const inputSegments = inputNormalized.split('.');
+            const filteredPolicies = this.policyEntries
+                .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+                .map(entry => entry.policy);
+            const effects = [...new Set(filteredPolicies.map(p => p.effect))].sort();
+            const items = filteredPolicies
+                .sort((a, b) => a.id.localeCompare(b.id))
+                .map(p => {
+                const effect = p.effect.padEnd(6, ' ');
+                const displayName = p.name === p.id ? 'Unnamed policy' : p.name;
+                return `  *   - ${effect} ${p.id}  "${displayName}"`;
+            })
+                .join('\n');
+            output += `
+ /**
+  * Permission: ${permission}
+  * Effects: ${effects.join(', ')}
+  * Policies:
+${items}
+  */
+`;
+            if (isEmpty) {
+                output += `  ['${permission}']: undefined;\n`;
+            }
+            else {
+                output += `  ['${permission}']: {\n`;
+                output += this.formatNestedObject(envObj, 4);
+                output += '  } | null | undefined;\n';
+            }
+        });
+        output += '}\n';
+        // complex
         return output;
     }
     /**
@@ -345,69 +664,126 @@ class AbilityTypeGenerator {
                 // Nested object
                 output += `${spaces}readonly ${key}: {\n`;
                 output += this.formatNestedObject(value, indent + 2);
-                output += `${spaces}};\n`;
+                output += `${spaces}} | null | undefined;\n`;
             }
             else {
                 // Primitive type
-                output += `${spaces}readonly ${key}: ${value};\n`;
+                const va = [String(value)];
+                let v = String(value);
+                if (!v.match(/unknown/)) {
+                    if (!v.match(/null/)) {
+                        va.push('null');
+                    }
+                    if (!v.match(/undefined/)) {
+                        va.push('undefined');
+                    }
+                }
+                output += `${spaces}readonly ${key}: ${va.join(' | ')} \n`;
             }
         });
         return output;
     }
 }
 
-class AbilityExplain {
-    type;
-    children;
-    name;
-    match;
-    constructor(config, children = []) {
-        this.type = config.type;
-        this.children = children;
-        this.name = config.name;
-        this.match = config.match;
-    }
-    toString(indent = 0) {
-        const pad = ' '.repeat(indent);
-        const mark = this.match.code === AbilityMatch.match.code ? '✓' : '✗';
-        let out = '';
-        if (this.type === 'policy') {
-            out += '\n';
+class AbilityHash {
+    static sha1(message) {
+        const msgBytes = AbilityHash.stringToBytes(message);
+        const msgBitLength = msgBytes.length * 8;
+        const withOne = new Uint8Array(msgBytes.length + 1);
+        withOne.set(msgBytes, 0);
+        withOne[msgBytes.length] = 0x80;
+        let zeroBytes = (56 - (withOne.length % 64) + 64) % 64;
+        const padded = new Uint8Array(withOne.length + zeroBytes + 8);
+        padded.set(withOne, 0);
+        const bitLenHigh = Math.floor(msgBitLength / 0x100000000);
+        const bitLenLow = msgBitLength >>> 0;
+        padded[padded.length - 8] = (bitLenHigh >>> 24) & 0xff;
+        padded[padded.length - 7] = (bitLenHigh >>> 16) & 0xff;
+        padded[padded.length - 6] = (bitLenHigh >>> 8) & 0xff;
+        padded[padded.length - 5] = bitLenHigh & 0xff;
+        padded[padded.length - 4] = (bitLenLow >>> 24) & 0xff;
+        padded[padded.length - 3] = (bitLenLow >>> 16) & 0xff;
+        padded[padded.length - 2] = (bitLenLow >>> 8) & 0xff;
+        padded[padded.length - 1] = bitLenLow & 0xff;
+        let h0 = 0x67452301;
+        let h1 = 0xefcdab89;
+        let h2 = 0x98badcfe;
+        let h3 = 0x10325476;
+        let h4 = 0xc3d2e1f0;
+        const w = new Array(80);
+        for (let i = 0; i < padded.length; i += 64) {
+            for (let j = 0; j < 16; j++) {
+                const idx = i + j * 4;
+                w[j] =
+                    (padded[idx] << 24) | (padded[idx + 1] << 16) | (padded[idx + 2] << 8) | padded[idx + 3];
+            }
+            for (let j = 16; j < 80; j++) {
+                w[j] = AbilityHash.leftRotate(w[j - 3] ^ w[j - 8] ^ w[j - 14] ^ w[j - 16], 1);
+            }
+            let a = h0;
+            let b = h1;
+            let c = h2;
+            let d = h3;
+            let e = h4;
+            for (let j = 0; j < 80; j++) {
+                let f;
+                let k;
+                if (j < 20) {
+                    f = (b & c) | (~b & d);
+                    k = 0x5a827999;
+                }
+                else {
+                    if (j < 40) {
+                        f = b ^ c ^ d;
+                        k = 0x6ed9eba1;
+                    }
+                    else {
+                        if (j < 60) {
+                            f = (b & c) | (b & d) | (c & d);
+                            k = 0x8f1bbcdc;
+                        }
+                        else {
+                            f = b ^ c ^ d;
+                            k = 0xca62c1d6;
+                        }
+                    }
+                }
+                const temp = (AbilityHash.leftRotate(a, 5) + f + e + k + (w[j] | 0)) | 0;
+                e = d;
+                d = c;
+                c = AbilityHash.leftRotate(b, 30);
+                b = a;
+                a = temp;
+            }
+            h0 = (h0 + a) | 0;
+            h1 = (h1 + b) | 0;
+            h2 = (h2 + c) | 0;
+            h3 = (h3 + d) | 0;
+            h4 = (h4 + e) | 0;
+        }
+        return [
+            AbilityHash.toHex32(h0),
+            AbilityHash.toHex32(h1),
+            AbilityHash.toHex32(h2),
+            AbilityHash.toHex32(h3),
+            AbilityHash.toHex32(h4),
+        ].join('');
+    }
+    static leftRotate(value, bits) {
+        return ((value << bits) | (value >>> (32 - bits))) >>> 0;
+    }
+    static toHex32(num) {
+        return (num >>> 0).toString(16).padStart(8, '0');
+    }
+    static stringToBytes(str) {
+        if (typeof TextEncoder !== 'undefined') {
+            const encoder = new TextEncoder();
+            return encoder.encode(str);
+        }
+        else {
+            const buf = Buffer.from(str, 'utf8');
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
         }
-        out += `${pad}${mark} ${this.type} «${this.name}» is ${this.match.code}`;
-        this.children.forEach(child => {
-            out += '\n' + child.toString(indent + 1);
-        });
-        return out;
-    }
-}
-class AbilityExplainRule extends AbilityExplain {
-    constructor(rule) {
-        super({
-            type: 'rule',
-            match: rule.state,
-            name: rule.name,
-        });
-    }
-}
-class AbilityExplainRuleSet extends AbilityExplain {
-    constructor(ruleSet) {
-        const children = ruleSet.rules.map(rule => new AbilityExplainRule(rule));
-        super({
-            type: 'ruleSet',
-            match: ruleSet.state,
-            name: ruleSet.name,
-        }, children);
-    }
-}
-class AbilityExplainPolicy extends AbilityExplain {
-    constructor(policy) {
-        const children = policy.ruleSet.map(ruleSet => new AbilityExplainRuleSet(ruleSet));
-        super({
-            type: 'policy',
-            name: policy.name,
-            match: policy.matchState,
-        }, children);
     }
 }
 
@@ -428,26 +804,34 @@ class AbilityPolicy {
      * one of the rules returns as «permit»
      */
     compareMethod = AbilityCompare.and;
-    /**
-     * Policy name
-     */
-    name;
     /**
      * Policy ID
      */
     id;
+    /**
+     * Policy name
+     */
+    name;
+    description;
     /**
      * Running the `enforce` or `resolve` method
      * will select only those from all passed policies that fall under the specified permission key.
      */
     permission;
+    priority = -1;
+    disabled;
+    tags;
     constructor(params) {
-        const { name, id, permission, effect, compareMethod = AbilityCompare.and } = params;
-        this.name = name;
-        this.id = id;
+        const { name, description, id, permission, effect, compareMethod = AbilityCompare.and, priority, disabled, tags, } = params;
         this.permission = permission;
+        this.description = description;
         this.effect = effect;
         this.compareMethod = compareMethod;
+        this.priority = typeof priority === 'number' ? priority : -1;
+        this.disabled = typeof disabled === 'boolean' ? disabled : false;
+        this.tags = (tags || []);
+        this.id = id || `p_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
     /**
      * Add rule set to the policy
@@ -467,6 +851,18 @@ class AbilityPolicy {
         }
         return this;
     }
+    /**
+     * Extract all rules of all ruleSets of this policy
+     */
+    extractRules() {
+        const rules = [];
+        for (const ruleSet of this.ruleSet) {
+            for (const rule of ruleSet.rules) {
+                rules.push(rule);
+            }
+        }
+        return rules;
+    }
     /**
      * Check if the policy is matched
      * @param resource - The resource to check
@@ -474,31 +870,57 @@ class AbilityPolicy {
      */
     check(resource, environment) {
         this.matchState = AbilityMatch.mismatch;
+        if (this.disabled) {
+            this.matchState = AbilityMatch.disabled;
+            return this.matchState;
+        }
         if (!this.ruleSet.length) {
             return this.matchState;
         }
-        const rulesetCheckStates = [];
-        for (const ruleSet of this.ruleSet) {
-            const state = ruleSet.check(resource, environment);
-            rulesetCheckStates.push(state);
-            if (AbilityCompare.and.isEqual(this.compareMethod) && AbilityMatch.mismatch.isEqual(state)) {
-                return this.matchState; // mismatch
+        const normalGroups = this.ruleSet.filter(g => !g.isExcept);
+        const exceptGroups = this.ruleSet.filter(g => g.isExcept);
+        const normalStates = [];
+        for (const group of normalGroups) {
+            if (group.disabled) {
+                continue;
             }
-            if (AbilityCompare.or.isEqual(this.compareMethod) && AbilityMatch.match.isEqual(state)) {
-                this.matchState = AbilityMatch.match;
+            const state = group.check(resource, environment);
+            normalStates.push(state);
+            if (AbilityCompare.and === this.compareMethod && AbilityMatch.mismatch === state) {
+                this.matchState = AbilityMatch.mismatch;
                 return this.matchState;
             }
-        }
-        if (AbilityCompare.and.isEqual(this.compareMethod)) {
-            if (rulesetCheckStates.every(s => AbilityMatch.match.isEqual(s))) {
+            if (AbilityCompare.or === this.compareMethod && AbilityMatch.match === state) {
                 this.matchState = AbilityMatch.match;
+                // break to check except-rule sets
+                break;
             }
         }
-        if (AbilityCompare.or.isEqual(this.compareMethod)) {
-            if (rulesetCheckStates.some(s => AbilityMatch.match.isEqual(s))) {
-                this.matchState = AbilityMatch.match;
+        // 3. Simple rule sets
+        let normalMatch = false;
+        if (AbilityCompare.and === this.compareMethod) {
+            normalMatch = normalStates.every(s => AbilityMatch.match === s);
+        }
+        else {
+            normalMatch = normalStates.some(s => AbilityMatch.match === s);
+        }
+        if (!normalMatch) {
+            this.matchState = AbilityMatch.mismatch;
+            return this.matchState;
+        }
+        // 4. except-rule sets
+        for (const group of exceptGroups) {
+            if (group.disabled) {
+                continue;
+            }
+            const state = group.check(resource, environment);
+            if (AbilityMatch.match === state) {
+                this.matchState = AbilityMatch.exceptMismatch;
+                return this.matchState;
             }
         }
+        // 5. match
+        this.matchState = AbilityMatch.match;
         return this.matchState;
     }
     explain() {
@@ -511,6 +933,8 @@ class AbilityPolicy {
         const policy = new AbilityPolicy({
             id: props.id ?? this.id,
             name: props.name ?? this.name,
+            description: props.description ?? this.description,
+            priority: typeof props.priority !== 'undefined' ? props.priority : this.priority,
             permission: props.permission ?? this.permission,
             effect: props.effect ?? this.effect,
             compareMethod: props.compareMethod ?? this.compareMethod,
@@ -521,124 +945,33 @@ class AbilityPolicy {
         }
         return policy;
     }
-}
-
-class AbilityPolicyEffect extends AbilityCode {
-    static deny = new AbilityPolicyEffect('deny');
-    static permit = new AbilityPolicyEffect('permit');
-}
-
-class AbilityResultState extends AbilityCode {
-    static allow = new AbilityResultState('allow');
-    static deny = new AbilityResultState('deny');
-    static neutral = new AbilityResultState('neutral');
-}
-
-class AbilityResult {
-    /**
-     * Already checked policies (after call the policy.check())
-     */
-    policies;
-    constructor(policies) {
-        this.policies = policies;
-    }
-    /**
-     * Returns a list of explanations for each policy involved in the ability evaluation.
-     * Each item describes how a specific policy contributed to the final permission result.
-     *
-     * Useful for debugging, logging, or building UI tools that visualize permission logic.
-     */
-    explain() {
-        return this.policies.map(policy => {
-            return new AbilityExplainPolicy(policy);
-        });
-    }
-    getLastMatchedPolicy() {
-        for (let i = this.policies.length - 1; i >= 0; i--) {
-            if (this.policies[i].matchState.isEqual(AbilityMatch.match)) {
-                return this.policies[i];
-            }
+    hash() {
+        const parts = [
+            `permission:${this.permission}`,
+            `effect:${this.effect}`,
+            `compareMethod:${this.compareMethod}`,
+            `priority:${this.priority}`,
+            `disabled:${this.disabled}`,
+        ];
+        if (this.tags && this.tags.length > 0) {
+            parts.push(`tags:${[...this.tags].sort().join(',')}`);
         }
-        return null;
-    }
-    getFinalState() {
-        let state = AbilityResultState.neutral;
-        for (const p of this.policies) {
-            if (p.matchState.isEqual(AbilityMatch.match)) {
-                if (p.effect.isEqual(AbilityPolicyEffect.permit)) {
-                    state = AbilityResultState.allow;
-                }
-                else if (p.effect.isEqual(AbilityPolicyEffect.deny)) {
-                    state = AbilityResultState.deny;
-                }
-            }
-            else if (p.matchState.isEqual(AbilityMatch.mismatch)) {
-                state = AbilityResultState.neutral;
-            }
+        if (this.ruleSet && this.ruleSet.length > 0) {
+            const ruleHashes = this.ruleSet.map(r => r.hash());
+            parts.push(`rules:${ruleHashes.sort().join('|')}`);
         }
-        return state;
-    }
-    isAllowed() {
-        return this.getFinalState().isEqual(AbilityResultState.allow);
-    }
-    isDenied() {
-        return this.getFinalState().isNotEqual(AbilityResultState.allow);
+        const str = parts.join(';');
+        return AbilityHash.sha1(str);
     }
 }
 
-class AbilityResolver {
-    policies;
-    constructor(
-    /**
-     * `Important!` The incorrect Resources type was intentionally passed to AbilityPolicy so that TypeScript could suggest the name of the permission and the structure of its resource in the parse method.
-     */
-    policyOrListOfPolicies) {
-        this.policies = Array.isArray(policyOrListOfPolicies)
-            ? policyOrListOfPolicies
-            : [policyOrListOfPolicies];
-    }
-    /**
-     * Resolve policy for the resource and permission key
-     *
-     * @param permission - Permission key
-     * @param resource - Resource
-     * @param environment
-     */
-    resolve(permission, resource, environment) {
-        const filteredPolicies = this.policies.filter(policy => AbilityResolver.isInPermissionContain(policy.permission, String(permission).replace(/^permission\./, '')));
-        for (const policy of filteredPolicies) {
-            const policyMatchState = policy.check(resource, environment);
-            if (policyMatchState === AbilityMatch.pending) {
-                throw new AbilityError(`The policy "${policy.name}" is still in a pending state. Make sure to call "check" to evaluate the policy before resolving permissions.`);
-            }
-        }
-        return new AbilityResult(filteredPolicies);
-    }
-    enforce(permission, resource, environment) {
-        const result = this.resolve(permission, resource, environment);
-        if (result.isDenied()) {
-            const lastPolicy = result.getLastMatchedPolicy();
-            if (lastPolicy) {
-                throw new AbilityError(`Permission denied by policy "${lastPolicy.name.toString()}"`);
-            }
-            // No policy matched → implicit deny
-            throw new AbilityError(`Permission denied: no matching policy found (implicit deny)`);
-        }
-    }
-    /**
-     * Check if the permission key is contained in another permission key
-     * @param permissionA - The first permission to check
-     * @param permissionB - The second permission to check
-     */
-    static isInPermissionContain(permissionA, permissionB) {
-        const A = permissionA.split('.');
-        const B = permissionB.split('.');
-        const [longer, shorter] = A.length >= B.length ? [A, B] : [B, A];
-        return shorter.every((chunk, i) => {
-            return chunk === '*' || longer[i] === '*' || chunk === longer[i];
-        });
-    }
+function brand$1(code) {
+    return code;
 }
+const AbilityPolicyEffect = {
+    deny: brand$1('deny'),
+    permit: brand$1('permit'),
+};
 
 /**
  * Represents a rule that defines a condition to be checked against a subject and resource.
@@ -654,8 +987,10 @@ class AbilityRule {
     resource;
     condition;
     name;
+    description;
     id;
     state = AbilityMatch.pending;
+    disabled;
     /**
      * Creates an instance of AbilityRule.
      * @param {string} params.id - The unique identifier of the rule.
@@ -663,33 +998,37 @@ class AbilityRule {
      * @param {AbilityCondition} params.condition - The condition to evaluate.
      * @param {string} params.subject - The subject of the rule.
      * @param {string} params.resource - The resource to compare against.
+     * @param {boolean} params.disabled - Disabling flag.
      * @param params
      */
     constructor(params) {
-        const { id, name, subject, resource, condition } = params;
-        this.name = name || `${JSON.stringify(subject)} ${condition.code} ${JSON.stringify(resource)}`;
-        this.id = id || this.name;
+        const { id, name, subject, resource, condition, disabled, description } = params;
+        this.description = description;
+        this.disabled = typeof disabled === 'boolean' ? disabled : false;
         this.subject = subject;
         this.resource = resource;
         this.condition = condition;
+        this.state = this.disabled ? AbilityMatch.disabled : this.state;
+        this.id = id || `r_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
-    isPrimitive(v) {
+    static isPrimitive(v) {
         return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null;
     }
-    isNumber(v) {
+    static isNumber(v) {
         return typeof v === 'number';
     }
-    isString(v) {
+    static isString(v) {
         return typeof v === 'string';
     }
-    valueLen = (v) => this.isString(v) || Array.isArray(v) ? v.length : null;
-    operatorHandlers = {
-        [AbilityCondition.always.literal]: () => true,
-        [AbilityCondition.never.literal]: () => false,
-        [AbilityCondition.equals.literal]: (a, b) => a === b,
-        [AbilityCondition.not_equals.literal]: (a, b) => a !== b,
-        [AbilityCondition.contains.literal]: (a, b) => {
-            if (Array.isArray(a) && this.isPrimitive(b)) {
+    static valueLen = (v) => this.isString(v) || Array.isArray(v) ? v.length : null;
+    static operatorHandlers = {
+        [toLiteral(AbilityCondition.always)]: () => true,
+        [toLiteral(AbilityCondition.never)]: () => false,
+        [toLiteral(AbilityCondition.equals)]: (a, b) => a === b,
+        [toLiteral(AbilityCondition.not_equals)]: (a, b) => a !== b,
+        [toLiteral(AbilityCondition.contains)]: (a, b) => {
+            if (Array.isArray(a) && AbilityRule.isPrimitive(b)) {
                 return a.includes(b);
             }
             if (Array.isArray(a) && Array.isArray(b)) {
@@ -697,8 +1036,8 @@ class AbilityRule {
             }
             return false;
         },
-        [AbilityCondition.not_contains.literal]: (a, b) => {
-            if (Array.isArray(a) && this.isPrimitive(b)) {
+        [toLiteral(AbilityCondition.not_contains)]: (a, b) => {
+            if (Array.isArray(a) && AbilityRule.isPrimitive(b)) {
                 return !a.includes(b);
             }
             if (Array.isArray(a) && Array.isArray(b)) {
@@ -706,8 +1045,8 @@ class AbilityRule {
             }
             return false;
         },
-        [AbilityCondition.in.literal]: (a, b) => {
-            if (this.isPrimitive(a) && Array.isArray(b)) {
+        [toLiteral(AbilityCondition.in)]: (a, b) => {
+            if (AbilityRule.isPrimitive(a) && Array.isArray(b)) {
                 return b.includes(a);
             }
             if (Array.isArray(a) && Array.isArray(b)) {
@@ -715,8 +1054,8 @@ class AbilityRule {
             }
             return false;
         },
-        [AbilityCondition.not_in.literal]: (a, b) => {
-            if (this.isPrimitive(a) && Array.isArray(b)) {
+        [toLiteral(AbilityCondition.not_in)]: (a, b) => {
+            if (AbilityRule.isPrimitive(a) && Array.isArray(b)) {
                 return !b.includes(a);
             }
             if (Array.isArray(a) && Array.isArray(b)) {
@@ -724,55 +1063,55 @@ class AbilityRule {
             }
             return false;
         },
-        [AbilityCondition.greater_than.literal]: (a, b) => {
-            return this.isNumber(a) && this.isNumber(b) ? a > b : false;
+        [toLiteral(AbilityCondition.greater_than)]: (a, b) => {
+            return AbilityRule.isNumber(a) && AbilityRule.isNumber(b) ? a > b : false;
         },
-        [AbilityCondition.less_than.literal]: (a, b) => {
-            return this.isNumber(a) && this.isNumber(b) ? a < b : false;
+        [toLiteral(AbilityCondition.less_than)]: (a, b) => {
+            return AbilityRule.isNumber(a) && AbilityRule.isNumber(b) ? a < b : false;
         },
-        [AbilityCondition.greater_or_equal.literal]: (a, b) => {
-            return this.isNumber(a) && this.isNumber(b) ? a >= b : false;
+        [toLiteral(AbilityCondition.greater_or_equal)]: (a, b) => {
+            return AbilityRule.isNumber(a) && AbilityRule.isNumber(b) ? a >= b : false;
         },
-        [AbilityCondition.less_or_equal.literal]: (a, b) => {
-            return this.isNumber(a) && this.isNumber(b) ? a <= b : false;
+        [toLiteral(AbilityCondition.less_or_equal)]: (a, b) => {
+            return AbilityRule.isNumber(a) && AbilityRule.isNumber(b) ? a <= b : false;
         },
-        [AbilityCondition.length_greater_than.literal]: (a, b) => {
-            const alen = this.valueLen(a);
+        [toLiteral(AbilityCondition.length_greater_than)]: (a, b) => {
+            const alen = AbilityRule.valueLen(a);
             if (alen === null) {
                 return false;
             }
-            if (this.isNumber(b)) {
+            if (AbilityRule.isNumber(b)) {
                 return alen > b;
             }
-            const bLen = this.valueLen(b);
+            const bLen = AbilityRule.valueLen(b);
             if (bLen !== null) {
                 return alen > bLen;
             }
             return false;
         },
-        [AbilityCondition.length_less_than.literal]: (a, b) => {
-            const alen = this.valueLen(a);
+        [toLiteral(AbilityCondition.length_less_than)]: (a, b) => {
+            const alen = AbilityRule.valueLen(a);
             if (alen === null) {
                 return false;
             }
-            if (this.isNumber(b)) {
+            if (AbilityRule.isNumber(b)) {
                 return alen < b;
             }
-            const bLen = this.valueLen(b);
+            const bLen = AbilityRule.valueLen(b);
             if (bLen !== null) {
                 return alen < bLen;
             }
             return false;
         },
-        [AbilityCondition.length_equals.literal]: (a, b) => {
-            const alen = this.valueLen(a);
+        [toLiteral(AbilityCondition.length_equals)]: (a, b) => {
+            const alen = AbilityRule.valueLen(a);
             if (alen === null) {
                 return false;
             }
-            if (this.isNumber(b)) {
+            if (AbilityRule.isNumber(b)) {
                 return alen === b;
             }
-            const bLen = this.valueLen(b);
+            const bLen = AbilityRule.valueLen(b);
             if (bLen !== null) {
                 return alen === bLen;
             }
@@ -785,8 +1124,12 @@ class AbilityRule {
      * @param environment
      */
     check(resource, environment) {
+        if (this.disabled) {
+            this.state = AbilityMatch.disabled;
+            return this.state;
+        }
         const [subjectValue, resourceValue] = this.extractValues(resource, environment);
-        const handler = this.operatorHandlers[this.condition.literal];
+        const handler = AbilityRule.operatorHandlers[toLiteral(this.condition)];
         const result = handler(subjectValue, resourceValue);
         this.state = result ? AbilityMatch.match : AbilityMatch.mismatch;
         return this.state;
@@ -833,46 +1176,75 @@ class AbilityRule {
         }
         return [subjectValue, resourceValue];
     }
+    static _pathCache = new Map();
+    static _parsePath(desc) {
+        const cached = AbilityRule._pathCache.get(desc);
+        if (cached)
+            return cached;
+        const parts = desc.split('.');
+        const segments = [];
+        for (const part of parts) {
+            const bracketIdx = part.indexOf('[');
+            if (bracketIdx !== -1) {
+                // формат: "prop[index]" (индекс может быть только числом)
+                const prop = part.slice(0, bracketIdx);
+                const indexStr = part.slice(bracketIdx + 1, -1);
+                const index = Number(indexStr);
+                segments.push({ prop, index });
+            }
+            else {
+                segments.push(part);
+            }
+        }
+        AbilityRule._pathCache.set(desc, segments);
+        return segments;
+    }
     /**
      * Get the value of the object by dot notation
      * @param resource - The object to get the value from
      * @param desc - The dot notation string
      */
     getDotNotationValue(resource, desc) {
-        const arr = desc.split('.');
-        while (arr.length && resource) {
-            const comp = arr.shift() || '';
-            const match = new RegExp('(.+)\\[([0-9]*)]').exec(comp);
-            if (match !== null && match.length == 3) {
-                const arrayData = {
-                    arrName: match[1],
-                    arrIndex: match[2],
-                };
-                if (resource[arrayData.arrName] !== undefined) {
-                    resource = resource[arrayData.arrName][arrayData.arrIndex];
-                }
-                else {
-                    resource = undefined;
-                }
+        if (resource == null) {
+            return undefined;
+        }
+        const segments = AbilityRule._parsePath(desc);
+        let current = resource;
+        for (const seg of segments) {
+            if (current == null) {
+                return undefined;
+            }
+            if (typeof seg === 'string') {
+                current = current[seg];
             }
             else {
-                resource = resource[comp];
+                const arr = current[seg.prop];
+                current = Array.isArray(arr) ? arr[seg.index] : undefined;
             }
         }
-        return resource;
+        return current;
     }
     toString() {
-        return `AbilityRule: ${this.name} condition: ${this.condition.code} subject: "${this.subject?.toString()}" resource: "${this.resource?.toString()}"`;
+        return `AbilityRule: ${this.name} condition: ${toLiteral(this.condition)} subject: "${this.subject?.toString()}" resource: "${this.resource?.toString()}"`;
     }
     copyWith(props) {
         return new AbilityRule({
             id: props.id ?? this.id,
             name: props.name ?? this.name,
+            description: props.description ?? this.description,
             subject: props.subject ?? this.subject,
             resource: props.resource ?? this.resource,
             condition: props.condition ?? this.condition,
         });
     }
+    hash() {
+        const parts = [];
+        parts.push(`subject:${this.subject}`);
+        parts.push(`resource:${JSON.stringify(this.resource)}`);
+        parts.push(`condition:${this.condition}`);
+        parts.push(`disabled:${this.disabled}`);
+        return AbilityHash.sha1(parts.join(';'));
+    }
     static equals(subject, resource) {
         return new AbilityRule({
             condition: AbilityCondition.equals,
@@ -969,15 +1341,22 @@ class AbilityRuleSet {
      * Group name
      */
     name;
+    description;
     /**
      * Group ID
      */
     id;
+    isExcept = false;
+    disabled;
     constructor(params) {
-        const { name, id, compareMethod } = params;
-        this.name = name || '';
-        this.id = id || this.name;
+        const { name, id, compareMethod, isExcept, disabled, description } = params;
+        this.description = description;
         this.compareMethod = compareMethod;
+        this.isExcept = isExcept;
+        this.disabled = typeof disabled === 'boolean' ? disabled : false;
+        this.state = this.disabled ? AbilityMatch.disabled : this.state;
+        this.id = id || `g_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
     addRule(rule) {
         this.rules.push(rule);
@@ -989,40 +1368,48 @@ class AbilityRuleSet {
     }
     check(resources, environment) {
         this.state = AbilityMatch.mismatch;
+        if (this.disabled) {
+            this.state = AbilityMatch.disabled;
+            return this.state;
+        }
         if (!this.rules.length) {
             return this.state;
         }
         const ruleCheckStates = [];
         for (const rule of this.rules) {
+            if (rule.disabled) {
+                continue;
+            }
             const state = rule.check(resources, environment);
             ruleCheckStates.push(state);
-            if (AbilityCompare.and.isEqual(this.compareMethod) && AbilityMatch.mismatch.isEqual(state)) {
+            if (AbilityCompare.and === this.compareMethod && AbilityMatch.mismatch === state) {
                 return this.state; // mismatch
             }
-            if (AbilityCompare.or.isEqual(this.compareMethod) && AbilityMatch.match.isEqual(state)) {
+            if (AbilityCompare.or === this.compareMethod && AbilityMatch.match === state) {
                 this.state = AbilityMatch.match;
                 return this.state;
             }
         }
-        if (AbilityCompare.and.isEqual(this.compareMethod)) {
-            if (ruleCheckStates.every(s => AbilityMatch.match.isEqual(s))) {
+        if (AbilityCompare.and === this.compareMethod) {
+            if (ruleCheckStates.every(s => AbilityMatch.match === s)) {
                 this.state = AbilityMatch.match;
             }
         }
-        if (AbilityCompare.or.isEqual(this.compareMethod)) {
-            if (ruleCheckStates.some(s => AbilityMatch.match.isEqual(s))) {
+        if (AbilityCompare.or === this.compareMethod) {
+            if (ruleCheckStates.some(s => AbilityMatch.match === s)) {
                 this.state = AbilityMatch.match;
             }
         }
         return this.state;
     }
     toString() {
-        return `AbilityRuleSet: ${this.name} compareMethod: ${this.compareMethod.code}, rules: ${this.rules.map(rule => rule.toString()).join('\n')}`;
+        return `AbilityRuleSet: ${this.name} compareMethod: ${this.compareMethod}, rules: ${this.rules.map(rule => rule.toString()).join('\n')}`;
     }
     copyWith(props) {
         const next = new AbilityRuleSet({
             id: props.id ?? this.id,
             name: props.name ?? this.name,
+            description: props.description ?? this.description,
             compareMethod: props.compareMethod ?? this.compareMethod,
         });
         const nextRules = props.rules ?? this.rules;
@@ -1031,6 +1418,16 @@ class AbilityRuleSet {
         }
         return next;
     }
+    hash() {
+        const ruleHashes = this.rules.map(r => r.hash()).sort();
+        const parts = [
+            `compareMethod:${this.compareMethod}`,
+            `isExcept:${this.isExcept}`,
+            `disabled:${this.disabled}`,
+            `rules:${ruleHashes.join('|')}`,
+        ];
+        return AbilityHash.sha1(parts.join(';'));
+    }
     static and(rules) {
         return new AbilityRuleSet({
             compareMethod: AbilityCompare.and,
@@ -1053,37 +1450,42 @@ class AbilityJSONParser {
         return configs.map(config => AbilityJSONParser.parsePolicy(config));
     }
     static parsePolicy(config) {
-        const { id, name, ruleSet, compareMethod, permission, effect } = config;
+        const { id, name, ruleSet, compareMethod, permission, effect, priority, disabled, tags } = config;
         // Create the empty policy
         const policy = new AbilityPolicy({
             name,
             id,
             permission: permission,
-            effect: new AbilityPolicyEffect(effect),
+            priority: priority,
+            effect: effect,
+            disabled,
+            tags,
         });
-        policy.compareMethod = new AbilityCompare(compareMethod);
+        policy.compareMethod = compareMethod;
         ruleSet.forEach(ruleSetConfig => {
             policy.addRuleSet(AbilityJSONParser.parseRuleSet(ruleSetConfig));
         });
         return policy;
     }
     static parseRule(config) {
-        const { id, name, subject, resource, condition } = config;
+        const { id, name, subject, resource, condition, disabled } = config;
         return new AbilityRule({
             id,
             name,
             subject,
             resource,
-            condition: new AbilityCondition(condition),
+            disabled,
+            condition,
         });
     }
     /**
      * Parse the config JSON format to Group class instance
      */
     static parseRuleSet(config) {
-        const { id, name, rules, compareMethod } = config;
+        const { id, name, rules, compareMethod, disabled } = config;
         const ruleSet = new AbilityRuleSet({
-            compareMethod: new AbilityCompare(compareMethod),
+            disabled,
+            compareMethod: compareMethod,
             name,
             id,
         });
@@ -1100,25 +1502,30 @@ class AbilityJSONParser {
             name: rule.name,
             subject: rule.subject,
             resource: rule.resource,
-            condition: rule.condition.code,
+            condition: rule.condition,
+            disabled: rule.disabled,
         };
     }
     static ruleSetToJSON(ruleSet) {
         return {
             id: ruleSet.id.toString(),
             name: ruleSet.name.toString(),
-            compareMethod: ruleSet.compareMethod.code.toString(),
+            compareMethod: ruleSet.compareMethod,
             rules: ruleSet.rules.map(rule => AbilityJSONParser.ruleToJSON(rule)),
+            disabled: ruleSet.disabled,
         };
     }
     static policyToJSON(policy) {
         return {
             id: policy.id.toString(),
             name: policy.name.toString(),
-            compareMethod: policy.compareMethod.code.toString(),
+            compareMethod: policy.compareMethod,
             ruleSet: policy.ruleSet.map(ruleSet => AbilityJSONParser.ruleSetToJSON(ruleSet)),
             permission: policy.permission,
-            effect: policy.effect.code,
+            effect: policy.effect,
+            priority: policy.priority,
+            disabled: policy.disabled,
+            tags: policy.tags,
         };
     }
     static toJSON(policies) {
@@ -1126,67 +1533,66 @@ class AbilityJSONParser {
     }
 }
 
-/**
- * Represents a single token produced by the Ability DSL lexer.
- * Each token carries a type (e.g., EFFECT, IDENTIFIER, STRING) and its raw string value.
- */
-class AbilityDSLToken extends AbilityCode {
-    /** The literal text of the token as it appeared in the input (e.g., "permit", "user.roles", "admin"). */
-    value = '';
-    /** The line number in DSL */
-    line = 1;
-    /** The column in dsl */
-    column = 1;
+function brand(code) {
+    return code;
+}
+const TokenTypes = {
+    EFFECT: brand('EFFECT'),
+    IF: brand('IF'),
+    PERMISSION: brand('PERMISSION'),
+    IDENTIFIER: brand('IDENTIFIER'),
+    COLON: brand('COLON'),
+    COMMA: brand('COMMA'),
+    DOT: brand('DOT'),
+    LBRACKET: brand('LBRACKET'),
+    RBRACKET: brand('RBRACKET'),
+    ALL: brand('ALL'),
+    ANY: brand('ANY'),
+    OF: brand('OF'),
+    EOF: brand('EOF'),
+    COMMENT: brand('COMMENT'),
+    EQ: brand('EQ'),
+    CONTAINS: brand('CONTAINS'),
+    IN: brand('IN'),
+    NOT_IN: brand('NOT_IN'),
+    NOT_CONTAINS: brand('NOT_CONTAINS'),
+    GT: brand('GT'),
+    GTE: brand('GTE'),
+    LT: brand('LT'),
+    LTE: brand('LTE'),
+    NULL: brand('NULL'),
+    EQ_NULL: brand('EQ_NULL'),
+    NOT_EQ_NULL: brand('NOT_EQ_NULL'),
+    NOT_EQ: brand('NOT_EQ'),
+    LEN_GT: brand('LEN_GT'),
+    LEN_LT: brand('LEN_LT'),
+    LEN_EQ: brand('LEN_EQ'),
+    ALWAYS: brand('ALWAYS'),
+    NEVER: brand('NEVER'),
+    EXCEPT: brand('EXCEPT'),
+    ANNOTATION: brand('ANNOTATION'),
+    STRING: brand('STRING'),
+    NUMBER: brand('NUMBER'),
+    BOOLEAN: brand('BOOLEAN'),
+    SYMBOL: brand('SYMBOL'),
+    KEYWORD: brand('KEYWORD'),
+    ALIAS: brand('ALIAS'),
+    UNKNOWN: brand('UNKNOWN'),
+};
+class AbilityDSLToken {
+    type;
+    value;
+    line;
+    column;
     constructor(type, value, line, column) {
-        super(type);
+        this.type = type;
         this.value = value;
         this.line = line;
         this.column = column;
     }
-    /**
-     * Returns a human-readable representation of the token, useful for debugging.
-     * Example output: "AbilityDSLToken([EFFECT] permit"
-     */
     toString() {
-        return `AbilityDSLToken([${this.code}] "${this.value}" at ${this.line}:${this.column})`;
-    }
-    static EFFECT = 'EFFECT';
-    static IF = 'IF';
-    static PERMISSION = 'PERMISSION';
-    static IDENTIFIER = 'IDENTIFIER';
-    static COLON = 'COLON';
-    static COMMA = 'COMMA';
-    static DOT = 'DOT';
-    static LBRACKET = 'LBRACKET';
-    static RBRACKET = 'RBRACKET';
-    static ALL = 'ALL';
-    static ANY = 'ANY';
-    static OF = 'OF';
-    static EOF = 'EOF';
-    static COMMENT = 'COMMENT';
-    static EQ = 'EQ';
-    static CONTAINS = 'CONTAINS';
-    static IN = 'IN';
-    static NOT_IN = 'NOT_IN';
-    static NOT_CONTAINS = 'NOT_CONTAINS';
-    static GT = 'GT';
-    static GTE = 'GTE';
-    static LT = 'LT';
-    static LTE = 'LTE';
-    static NULL = 'NULL';
-    static EQ_NULL = 'EQ_NULL';
-    static NOT_EQ_NULL = 'NOT_EQ_NULL';
-    static LEN_GT = 'LEN_GT';
-    static LEN_LT = 'LEN_LT';
-    static LEN_EQ = 'LEN_EQ';
-    static NOT_EQ = 'NOT_EQ';
-    static ALWAYS = 'ALWAYS';
-    static NEVER = 'NEVER';
-    static STRING = 'STRING';
-    static NUMBER = 'NUMBER';
-    static BOOLEAN = 'BOOLEAN';
-    static SYMBOL = 'SYMBOL';
-    static KEYWORD = 'KEYWORD';
+        return `AbilityDSLToken([${this.type}] "${this.value}" at ${this.line}:${this.column})`;
+    }
 }
 
 class AbilityDSLLexer {
@@ -1195,7 +1601,6 @@ class AbilityDSLLexer {
     tokens = [];
     line = 1;
     column = 1;
-    // Список ключевых слов
     keywords = new Set([
         'if',
         'all',
@@ -1226,6 +1631,8 @@ class AbilityDSLLexer {
         'than',
         'always',
         'never',
+        'except',
+        'alias',
     ]);
     constructor(input) {
         this.input = input;
@@ -1236,6 +1643,10 @@ class AbilityDSLLexer {
             if (this.isAtEnd())
                 break;
             const char = this.peek();
+            if (char === '@') {
+                this.tokens.push(this.readAnnotation());
+                continue;
+            }
             if (char === '#') {
                 this.tokens.push(this.readComment());
                 continue;
@@ -1258,7 +1669,7 @@ class AbilityDSLLexer {
             }
             throw new Error(`Unexpected character '${char}' at ${this.line}:${this.column}`);
         }
-        this.tokens.push(new AbilityDSLToken(AbilityDSLToken.EOF, '', this.line, this.column));
+        this.tokens.push(new AbilityDSLToken(TokenTypes.EOF, '', this.line, this.column));
         return this.tokens;
     }
     readComment() {
@@ -1269,7 +1680,69 @@ class AbilityDSLLexer {
         while (!this.isAtEnd() && !this.isNewline()) {
             value += this.advance();
         }
-        return new AbilityDSLToken(AbilityDSLToken.COMMENT, value.trim(), startLine, startColumn);
+        return new AbilityDSLToken(TokenTypes.COMMENT, value.trim(), startLine, startColumn);
+    }
+    // private readAlias(): AbilityDSLToken {
+    //   const startLine = this.line;
+    //   const startColumn = this.column;
+    //
+    //   this.advance(); // skip "alias" keyword
+    //
+    //   // Read colon
+    //   this.readSymbol();
+    //
+    //   let value = '';
+    //   while (!this.isAtEnd() && !this.isNewline()) {
+    //     value += this.advance();
+    //   }
+    //   return new AbilityDSLToken(TokenTypes.ALIAS, value.trim(), startLine, startColumn);
+    // }
+    readAnnotation() {
+        const startLine = this.line;
+        const startColumn = this.column;
+        let raw = '';
+        // читаем всю строку после @
+        while (!this.isAtEnd() && !this.isNewline()) {
+            raw += this.advance();
+        }
+        raw = raw.trim();
+        // parse literals
+        let result = '';
+        let i = 0;
+        let inString = false;
+        let quote = null;
+        let escaped = false;
+        while (i < raw.length) {
+            const ch = raw[i];
+            if (inString) {
+                if (escaped) {
+                    result += ch;
+                    escaped = false;
+                }
+                else if (ch === '\\') {
+                    escaped = true;
+                }
+                else if (ch === quote) {
+                    inString = false;
+                    quote = null;
+                }
+                else {
+                    result += ch;
+                }
+                i++;
+                continue;
+            }
+            // start of string
+            if (ch === '"' || ch === "'") {
+                inString = true;
+                quote = ch;
+                i++;
+                continue;
+            }
+            result += ch;
+            i++;
+        }
+        return new AbilityDSLToken(TokenTypes.ANNOTATION, result.trim(), startLine, startColumn);
     }
     readString() {
         const startLine = this.line;
@@ -1289,7 +1762,7 @@ class AbilityDSLLexer {
                 continue;
             }
             if (char === quote) {
-                return new AbilityDSLToken(AbilityDSLToken.STRING, value, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.STRING, value, startLine, startColumn);
             }
             value += char;
         }
@@ -1303,7 +1776,7 @@ class AbilityDSLLexer {
             this.advance();
         }
         const value = this.input.slice(start, this.pos);
-        return new AbilityDSLToken(AbilityDSLToken.NUMBER, value, startLine, startColumn);
+        return new AbilityDSLToken(TokenTypes.NUMBER, value, startLine, startColumn);
     }
     readSymbol() {
         const startLine = this.line;
@@ -1311,41 +1784,41 @@ class AbilityDSLLexer {
         const char = this.advance();
         switch (char) {
             case '.':
-                return new AbilityDSLToken(AbilityDSLToken.DOT, char, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.DOT, char, startLine, startColumn);
             case ':':
-                return new AbilityDSLToken(AbilityDSLToken.COLON, char, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.COLON, char, startLine, startColumn);
             case ',':
-                return new AbilityDSLToken(AbilityDSLToken.COMMA, char, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.COMMA, char, startLine, startColumn);
             case '[':
-                return new AbilityDSLToken(AbilityDSLToken.LBRACKET, char, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.LBRACKET, char, startLine, startColumn);
             case ']':
-                return new AbilityDSLToken(AbilityDSLToken.RBRACKET, char, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.RBRACKET, char, startLine, startColumn);
             case '>':
                 if (this.peek() === '=') {
                     this.advance();
-                    return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '>=', startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.SYMBOL, '>=', startLine, startColumn);
                 }
-                return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '>', startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.SYMBOL, '>', startLine, startColumn);
             case '<':
                 if (this.peek() === '=') {
                     this.advance();
-                    return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '<=', startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.SYMBOL, '<=', startLine, startColumn);
                 }
                 if (this.peek() === '>') {
                     this.advance();
-                    return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '<>', startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.SYMBOL, '<>', startLine, startColumn);
                 }
-                return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '<', startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.SYMBOL, '<', startLine, startColumn);
             case '=':
                 if (this.peek() === '=') {
                     this.advance();
-                    return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '==', startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.SYMBOL, '==', startLine, startColumn);
                 }
-                return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '=', startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.SYMBOL, '=', startLine, startColumn);
             case '!':
                 if (this.peek() === '=') {
                     this.advance();
-                    return new AbilityDSLToken(AbilityDSLToken.SYMBOL, '!=', startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.SYMBOL, '!=', startLine, startColumn);
                 }
                 throw new Error(`Unexpected symbol '!' at ${this.line}:${this.column}`);
             default:
@@ -1372,60 +1845,66 @@ class AbilityDSLLexer {
         }
         const word = this.input.slice(start, this.pos);
         if (word === 'always') {
-            return new AbilityDSLToken(AbilityDSLToken.ALWAYS, word, startLine, startColumn);
+            return new AbilityDSLToken(TokenTypes.ALWAYS, word, startLine, startColumn);
         }
         if (word === 'never') {
-            return new AbilityDSLToken(AbilityDSLToken.NEVER, word, startLine, startColumn);
+            return new AbilityDSLToken(TokenTypes.NEVER, word, startLine, startColumn);
         }
         // Если есть точка — это путь (identifier или permission)
         if (word.includes('.')) {
             const last = this.tokens[this.tokens.length - 1];
-            if (last?.code === AbilityDSLToken.EFFECT) {
+            if (last?.type === TokenTypes.EFFECT) {
                 if (word.startsWith('permission.')) {
-                    return new AbilityDSLToken(AbilityDSLToken.PERMISSION, word, startLine, startColumn);
+                    return new AbilityDSLToken(TokenTypes.PERMISSION, word, startLine, startColumn);
                 }
             }
-            return new AbilityDSLToken(AbilityDSLToken.IDENTIFIER, word, startLine, startColumn);
+            return new AbilityDSLToken(TokenTypes.IDENTIFIER, word, startLine, startColumn);
         }
         // Ключевые слова
         if (this.keywords.has(word)) {
             // Эффекты
             if (word === 'permit' || word === 'allow') {
-                return new AbilityDSLToken(AbilityDSLToken.EFFECT, 'permit', startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.EFFECT, 'permit', startLine, startColumn);
             }
             if (word === 'deny' || word === 'forbidden') {
-                return new AbilityDSLToken(AbilityDSLToken.EFFECT, 'deny', startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.EFFECT, 'deny', startLine, startColumn);
             }
             // Групповые ключевые слова
             if (word === 'all') {
-                return new AbilityDSLToken(AbilityDSLToken.ALL, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.ALL, word, startLine, startColumn);
             }
             if (word === 'any') {
-                return new AbilityDSLToken(AbilityDSLToken.ANY, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.ANY, word, startLine, startColumn);
             }
             if (word === 'of') {
-                return new AbilityDSLToken(AbilityDSLToken.OF, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.OF, word, startLine, startColumn);
             }
             if (word === 'if') {
-                return new AbilityDSLToken(AbilityDSLToken.IF, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.IF, word, startLine, startColumn);
             }
             // Булевы и null
             if (word === 'true' || word === 'false') {
-                return new AbilityDSLToken(AbilityDSLToken.BOOLEAN, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.BOOLEAN, word, startLine, startColumn);
             }
             if (word === 'null') {
-                return new AbilityDSLToken(AbilityDSLToken.NULL, word, startLine, startColumn);
+                return new AbilityDSLToken(TokenTypes.NULL, word, startLine, startColumn);
+            }
+            if (word === 'except') {
+                return new AbilityDSLToken(TokenTypes.EXCEPT, word, startLine, startColumn);
+            }
+            if (word === 'alias') {
+                return new AbilityDSLToken(TokenTypes.ALIAS, word, startLine, startColumn);
             }
             // Остальные ключевые слова (contains, in, equals, greater, less, not, is, or, than, equal)
-            return new AbilityDSLToken(AbilityDSLToken.KEYWORD, word, startLine, startColumn);
+            return new AbilityDSLToken(TokenTypes.KEYWORD, word, startLine, startColumn);
         }
         // Если после EFFECT и нет точки — действие (например, "create")
         const lastToken = this.tokens[this.tokens.length - 1];
-        if (lastToken?.code === AbilityDSLToken.EFFECT) {
-            return new AbilityDSLToken(AbilityDSLToken.PERMISSION, word, startLine, startColumn);
+        if (lastToken?.type === TokenTypes.EFFECT) {
+            return new AbilityDSLToken(TokenTypes.PERMISSION, word, startLine, startColumn);
         }
         // Обычный идентификатор
-        return new AbilityDSLToken(AbilityDSLToken.IDENTIFIER, word, startLine, startColumn);
+        return new AbilityDSLToken(TokenTypes.IDENTIFIER, word, startLine, startColumn);
     }
     skipWhitespace() {
         while (!this.isAtEnd() && /\s/.test(this.peek())) {
@@ -1481,47 +1960,256 @@ class AbilityDSLSyntaxError extends Error {
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, AbilityDSLSyntaxError);
         }
-        this._originalStack = this.stack;
-        this._formattedMessage = this.formatMessage();
-        Object.defineProperty(this, 'stack', {
-            get: () => this._formattedMessage,
-            configurable: true,
-        });
+        this._originalStack = this.stack;
+        this._formattedMessage = this.formatMessage();
+        Object.defineProperty(this, 'stack', {
+            get: () => this._formattedMessage,
+            configurable: true,
+        });
+    }
+    static supportsColor() {
+        return typeof process !== 'undefined' && process.stdout?.isTTY;
+    }
+    formatMessage() {
+        const useColor = AbilityDSLSyntaxError.supportsColor();
+        const BOLD = useColor ? '\x1b[1m' : '';
+        const RED = useColor ? '\x1b[31m' : '';
+        const ORANGE = useColor ? '\x1b[33;1m' : '';
+        const GRAY = useColor ? '\x1b[90m' : '';
+        const RESET = useColor ? '\x1b[0m' : '';
+        const lines = this.context.split('\n');
+        // Find line with ^
+        const pointerIndex = lines.findIndex(l => l.includes('^') || l.includes('~'));
+        const commentIndex = lines.findIndex(l => l.trim().includes('#'));
+        const formattedLines = lines.map((line, idx) => {
+            if (idx === pointerIndex - 1) {
+                // Error line
+                return `${BOLD}${ORANGE}${line}${RESET}`;
+            }
+            if (idx === pointerIndex) {
+                // Error with ~~~~~
+                return `${RED}${line}${RESET}`;
+            }
+            // Comments # ...
+            if (idx === commentIndex) {
+                return `${GRAY}${line}${RESET}`;
+            }
+            return line;
+        });
+        const contextBlock = formattedLines.join('\n');
+        return `${BOLD}${RED}${this.name}: ${this.details}${RESET}\n\n` + contextBlock;
+    }
+    toString() {
+        return this._formattedMessage;
+    }
+}
+
+class AbilityDSLTokenStream {
+    tokens;
+    pos = 0;
+    dsl;
+    marks = [];
+    lastToken = null;
+    next() {
+        const token = this.tokens[this.pos++];
+        this.lastToken = token;
+        return token;
+    }
+    prev() {
+        if (this.pos === 0) {
+            return null;
+        }
+        const token = this.tokens[this.pos--];
+        this.lastToken = token;
+        return token;
+    }
+    lookPrev() {
+        return this.lastToken;
+    }
+    constructor(tokens, dsl) {
+        this.tokens = tokens;
+        this.dsl = dsl;
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    eof() {
+        return this.peek().type === TokenTypes.EOF;
+    }
+    check(type) {
+        if (this.eof()) {
+            return false;
+        }
+        return this.peek().type === type;
+    }
+    match(type) {
+        if (this.check(type)) {
+            return this.next();
+        }
+        return null;
+    }
+    expect(type, message) {
+        const token = this.peek();
+        if (token && token.type === type) {
+            return this.next();
+        }
+        this.syntaxError(message, token, [type]);
+    }
+    expectOneOf(types, message) {
+        const token = this.peek();
+        for (const t of types) {
+            if (token && token.type === t) {
+                return this.next();
+            }
+        }
+        this.syntaxError(message, token, types);
+    }
+    mark() {
+        this.marks.push(this.pos);
+    }
+    reset() {
+        const pos = this.marks.pop();
+        if (pos !== undefined) {
+            this.pos = pos;
+        }
+    }
+    commit() {
+        this.marks.pop();
+    }
+    syntaxError(details, token, expected) {
+        const lines = this.dsl.split(/\r?\n/);
+        const lineIdx = token.line - 1;
+        const lineBefore = lineIdx > 0 ? lines[lineIdx - 1] : '';
+        const current = lines[lineIdx];
+        const linesAfter = lineIdx + 1 < lines.length ? lines[lineIdx + 1] : '';
+        const wave = ' '.repeat(Math.max(0, token.column - 1)) + '~'.repeat(token.value.length);
+        const lineNumWidth = String(token.line + 1).length;
+        const num = (n) => String(n).padStart(lineNumWidth, ' ');
+        let context = '';
+        if (lineBefore.trim() !== '') {
+            context += `${num(token.line - 1)} | ${lineBefore}\n`;
+        }
+        context += `${num(token.line)} | ${current}\n`;
+        context += `${' '.repeat(lineNumWidth)} | ${wave}\n`;
+        if (linesAfter.trim() !== '') {
+            context += `${num(token.line + 1)} | ${linesAfter}`;
+        }
+        let finalDetails = details;
+        if (expected && expected?.length > 0) {
+            const actual = token.value;
+            const suggestion = this.suggest(actual, expected);
+            const detailsMsg = `${details}\nDetails: Unexpected value token \`${actual}\``;
+            finalDetails = suggestion ? `${detailsMsg} Did you mean \`${suggestion}\`?` : detailsMsg;
+        }
+        throw new AbilityDSLSyntaxError(token.line, token.column, context + '\n', finalDetails);
+    }
+    suggest(actual, expectedTypes) {
+        const candidates = [];
+        for (const type of expectedTypes) {
+            candidates.push(type);
+        }
+        const uniqueCandidates = [...new Set(candidates)];
+        let best = null;
+        let bestDist = 3;
+        for (const candidate of uniqueCandidates) {
+            const d = this.levenshteinDistance(actual.toLowerCase(), candidate.toLowerCase());
+            if (d < bestDist) {
+                bestDist = d;
+                best = candidate;
+            }
+        }
+        return best;
+    }
+    levenshteinDistance(a, b) {
+        const matrix = Array.from({ length: b.length + 1 }, () => Array.from({ length: a.length + 1 }, () => 0));
+        for (let i = 0; i <= a.length; i++)
+            matrix[0][i] = i;
+        for (let j = 0; j <= b.length; j++)
+            matrix[j][0] = j;
+        for (let j = 1; j <= b.length; j++) {
+            for (let i = 1; i <= a.length; i++) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                matrix[j][i] = Math.min(matrix[j][i - 1] + 1, matrix[j - 1][i] + 1, matrix[j - 1][i - 1] + cost);
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+}
+
+class AbilityDSLAnnotations {
+    store = {
+        id: undefined,
+        name: undefined,
+        priority: undefined,
+        description: undefined,
+        disabled: undefined,
+        tags: undefined,
+    };
+    get(key) {
+        return this.store[key] ?? null;
+    }
+    set(key, value, token) {
+        if (value === null) {
+            this.store[key] = undefined;
+        }
+        else {
+            this.store[key] = {
+                key,
+                value,
+                token,
+            };
+        }
+        return this;
     }
-    static supportsColor() {
-        return typeof process !== 'undefined' && process.stdout?.isTTY;
+    clear() {
+        for (const key of Object.keys(this.store)) {
+            this.store[key] = undefined;
+        }
+    }
+    clone() {
+        const cloned = new AbilityDSLAnnotations();
+        for (const key of Object.keys(this.store)) {
+            const entry = this.store[key];
+            cloned.store[key] = entry
+                ? { ...entry }
+                : undefined;
+        }
+        return cloned;
+    }
+    // convenience getters
+    get id() { return this.get('id'); }
+    get name() { return this.get('name'); }
+    get description() { return this.get('description'); }
+    get priority() { return this.get('priority'); }
+    get disabled() { return this.get('disabled'); }
+    get tags() { return this.get('tags'); }
+    // convenience setters
+    setID(v, t) { return this.set('id', v, t); }
+    setName(v, t) { return this.set('name', v, t); }
+    setDescription(v, t) { return this.set('description', v, t); }
+    setPriority(v, t) { return this.set('priority', v, t); }
+    setDisabled(v, t) { return this.set('disabled', v, t); }
+    setTags(v, t) { return this.set('tags', v, t); }
+}
+
+const AnnotationAllowed = {
+    policy: new Set(["id", "name", "description", "priority", "disabled", "tags"]),
+    ruleSet: new Set(["id", "name", "description", "disabled"]),
+    rule: new Set(["id", "name", "disabled"]),
+    alias: new Set(["name", "disabled"]),
+};
+
+class AbilityDSLAliases {
+    store = new Map();
+    get(alias) {
+        return this.store.get(alias) || null;
     }
-    formatMessage() {
-        const useColor = AbilityDSLSyntaxError.supportsColor();
-        const BOLD = useColor ? '\x1b[1m' : '';
-        const RED = useColor ? '\x1b[31m' : '';
-        const ORANGE = useColor ? '\x1b[33;1m' : '';
-        const GRAY = useColor ? '\x1b[90m' : '';
-        const RESET = useColor ? '\x1b[0m' : '';
-        const lines = this.context.split('\n');
-        // Find line with ^
-        const pointerIndex = lines.findIndex(l => l.includes('^') || l.includes('~'));
-        const commentIndex = lines.findIndex(l => l.trim().includes('#'));
-        const formattedLines = lines.map((line, idx) => {
-            if (idx === pointerIndex - 1) {
-                // Error line
-                return `${BOLD}${ORANGE}${line}${RESET}`;
-            }
-            if (idx === pointerIndex) {
-                // Error with ~~~~~
-                return `${RED}${line}${RESET}`;
-            }
-            // Comments # ...
-            if (idx === commentIndex) {
-                return `${GRAY}${line}${RESET}`;
-            }
-            return line;
-        });
-        const contextBlock = formattedLines.join('\n');
-        return `${BOLD}${RED}${this.name}: ${this.details}${RESET}\n\n` + contextBlock;
+    set(alias, rule) {
+        this.store.set(alias, rule);
+        return this;
     }
-    toString() {
-        return this._formattedMessage;
+    has(alias) {
+        return this.store.has(alias);
     }
 }
 
@@ -1543,12 +2231,9 @@ class AbilityDSLSyntaxError extends Error {
  */
 class AbilityDSLParser {
     dsl;
-    tokens = [];
-    pos = 0;
-    annotationBuffer = {
-        name: null,
-        description: null,
-    };
+    stream;
+    annBuffer = new AbilityDSLAnnotations();
+    aliasBuffer = new AbilityDSLAliases();
     constructor(dsl) {
         this.dsl = dsl;
     }
@@ -1557,17 +2242,19 @@ class AbilityDSLParser {
      * @returns Array of AbilityPolicy instances.
      */
     parse() {
-        // Tokenize the entire DSL string.
-        this.tokens = new AbilityDSLLexer(this.dsl).tokenize();
-        this.pos = 0;
+        this.annBuffer.clear();
+        // 1. Лексер → токены
+        const tokens = new AbilityDSLLexer(this.dsl).tokenize();
+        // 2. Создаём TokenStream
+        this.stream = new AbilityDSLTokenStream(tokens, this.dsl);
         const policies = [];
-        // Keep parsing until we've consumed all tokens.
-        while (!this.isAtEnd()) {
+        while (!this.stream.eof()) {
             this.consumeLeadingComments();
-            // Every policy must start with an EFFECT token.
+            this.consumeLeadingAnnotations();
+            this.consumeLeadingAliases();
             if (!this.isStartOfPolicy()) {
-                const token = this.peek();
-                this.syntaxError(`Expected policy, got ${token.code}.`, token, ['EFFECT']);
+                const token = this.stream.peek();
+                this.stream.syntaxError(`Expected policy, got ${token.type}.`, token, [TokenTypes.EFFECT]);
             }
             policies.push(this.parsePolicy());
         }
@@ -1584,31 +2271,37 @@ class AbilityDSLParser {
      */
     parsePolicy() {
         this.consumeLeadingComments();
-        const meta = this.takeAnnotations();
+        this.consumeLeadingAnnotations();
+        this.consumeLeadingAliases();
+        const annotations = this.takeAnnotations('policy');
         // Effect: "permit" or "deny"
-        const effectToken = this.consume(AbilityDSLToken.EFFECT, 'Expected effect');
+        const effectToken = this.stream.expect(TokenTypes.EFFECT, 'Expected effect');
         const effect = effectToken.value;
         // Permission: e.g. "order.update"
-        const permissionToken = this.consume(AbilityDSLToken.PERMISSION, 'Expected permission');
+        const permissionToken = this.stream.expect(TokenTypes.PERMISSION, 'Expected permission');
         const permission = permissionToken.value;
         if (!permission.startsWith('permission.')) {
-            return this.syntaxError(`Unexpected token. The permission key, must be starts with prefix \`permission.\`, but got \`${permission}\`.\nDid you mean \`permission.${permission}\`?`, permissionToken);
+            return this.stream.syntaxError(`Unexpected token. The permission key, must be starts with prefix \`permission.\`, but got \`${permission}\`.\nDid you mean \`permission.${permission}\`?`, permissionToken);
         }
         // "if" keyword
-        this.consume(AbilityDSLToken.IF, 'Expected "if"');
+        this.stream.expect(TokenTypes.IF, 'Expected "if"');
         // Group selector: "all" or "any" – determines how the top‑level rule sets are combined.
-        const compareToken = this.consumeOneOf([AbilityDSLToken.ALL, AbilityDSLToken.ANY], 'Expected "all" or "any"');
-        const compareMethod = compareToken.code === AbilityDSLToken.ALL ? AbilityCompare.and : AbilityCompare.or;
+        const compareToken = this.stream.expectOneOf([TokenTypes.ALL, TokenTypes.ANY], 'Expected "all" or "any"');
+        const compareMethod = compareToken.type === TokenTypes.ALL ? AbilityCompare.and : AbilityCompare.or;
         // Colon after the group keyword
-        this.consume(AbilityDSLToken.COLON, 'Expected ":"');
+        this.stream.expect(TokenTypes.COLON, 'Expected ":"');
         // Parse the list of rule sets (each "all of:" or "any of:" block)
         const ruleSets = this.parseRuleSets(compareMethod);
         // Construct the policy instance.
         return new AbilityPolicy({
-            id: `${effect}:${permission}:${Math.random()}`,
-            name: meta.name ?? `${effect} ${permission}`,
+            id: annotations.id?.value || null,
+            name: annotations.name?.value || null,
+            description: annotations.description?.value || null,
+            priority: annotations.priority?.value || null,
             permission: permission.replace(/^permission\./, ''),
             effect: effect === 'permit' ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny,
+            disabled: annotations.disabled?.value ?? undefined,
+            tags: annotations.tags?.value ?? undefined,
             compareMethod,
         }).addRuleSets(ruleSets);
     }
@@ -1620,32 +2313,41 @@ class AbilityDSLParser {
      */
     parseRuleSets(policyCompareMethod) {
         const sets = [];
-        while (!this.isAtEnd() && !this.isStartOfPolicy()) {
+        while (!this.stream.eof() && !this.isStartOfPolicy()) {
             this.consumeLeadingComments();
+            this.consumeLeadingAnnotations();
+            // Если начинается новая except группа — парсим её
+            if (this.isStartOfExcept()) {
+                sets.push(this.parseExceptGroup(policyCompareMethod));
+                continue;
+            }
             // Если начинается новая группа — парсим её
             if (this.isStartOfGroup()) {
                 sets.push(this.parseGroup());
                 continue;
             }
-            // Иначе — implicit group (all-of по умолчанию)
-            const meta = this.takeAnnotations();
+            const annotation = this.takeAnnotations('ruleSet');
             const group = new AbilityRuleSet({
+                id: annotation.id?.value || null,
                 compareMethod: policyCompareMethod,
-                name: meta.name,
+                name: annotation.name?.value ?? null,
+                description: annotation.description?.value || null,
+                disabled: annotation.disabled?.value ?? undefined,
             });
             // Читаем правила implicit-группы
-            while (!this.isAtEnd()) {
+            while (!this.stream.eof()) {
                 this.consumeLeadingComments();
-                if (this.isStartOfGroup() || this.isStartOfPolicy()) {
+                this.consumeLeadingAnnotations();
+                if (this.isStartOfGroup() || this.isStartOfPolicy() || this.isStartOfExcept()) {
                     break;
                 }
-                if (this.check(AbilityDSLToken.IDENTIFIER) ||
-                    this.check(AbilityDSLToken.ALWAYS) ||
-                    this.check(AbilityDSLToken.NEVER)) {
+                if (this.stream.check(TokenTypes.IDENTIFIER) ||
+                    this.stream.check(TokenTypes.ALWAYS) ||
+                    this.stream.check(TokenTypes.NEVER)) {
                     group.addRule(this.parseRule());
                 }
                 else {
-                    this.syntaxError(`Unexpected token in implicit group: ${this.peek().code}`, this.peek());
+                    this.stream.syntaxError(`Unexpected token in implicit group: ${this.stream.peek().type}`, this.stream.peek());
                 }
             }
             sets.push(group);
@@ -1657,24 +2359,83 @@ class AbilityDSLParser {
      */
     parseGroup() {
         this.consumeLeadingComments();
-        const meta = this.takeAnnotations();
-        const compareToken = this.consumeOneOf([AbilityDSLToken.ALL, AbilityDSLToken.ANY, AbilityDSLToken.ALWAYS, AbilityDSLToken.NEVER], 'Expected "all" or "any" or "always" or "never"');
-        const compareMethod = compareToken.code === AbilityDSLToken.ALL ? AbilityCompare.and : AbilityCompare.or;
-        if (this.check(AbilityDSLToken.OF)) {
-            this.advance();
-        }
-        this.consume(AbilityDSLToken.COLON, 'Expected ":"');
-        const group = new AbilityRuleSet({ compareMethod, name: meta.name });
-        while (!this.isAtEnd()) {
+        this.consumeLeadingAnnotations();
+        const annotations = this.takeAnnotations('ruleSet');
+        const compareToken = this.stream.expectOneOf([TokenTypes.ALL, TokenTypes.ANY, TokenTypes.ALWAYS, TokenTypes.NEVER], 'Expected "all" or "any" or "always" or "never"');
+        const compareMethod = compareToken.type === TokenTypes.ALL ? AbilityCompare.and : AbilityCompare.or;
+        if (this.stream.check(TokenTypes.OF)) {
+            this.stream.next();
+        }
+        this.stream.expect(TokenTypes.COLON, 'Expected ":"');
+        const group = new AbilityRuleSet({
+            id: annotations.id?.value || null,
+            compareMethod,
+            name: annotations.name?.value || null,
+            description: annotations.description?.value || null,
+            disabled: annotations.disabled?.value ?? undefined,
+        });
+        while (!this.stream.eof()) {
             this.consumeLeadingComments();
+            this.consumeLeadingAnnotations();
+            if (this.isStartOfExcept()) {
+                break;
+            }
             if (this.isStartOfGroup() || this.isStartOfPolicy()) {
                 break;
             }
-            if (this.check(AbilityDSLToken.IDENTIFIER)) {
+            if (this.stream.check(TokenTypes.IDENTIFIER)) {
+                group.addRule(this.parseRule());
+            }
+            else {
+                this.stream.syntaxError(`Unexpected token in group: ${this.stream.peek().type}`, this.stream.peek());
+            }
+        }
+        return group;
+    }
+    // -------------------------------------------------------------------------
+    // #region Except RuleSet parsing
+    // -------------------------------------------------------------------------
+    parseExceptGroup(policyCompareMethod) {
+        this.consumeLeadingComments();
+        this.consumeLeadingAnnotations();
+        const annotations = this.takeAnnotations('ruleSet');
+        // consume "except"
+        this.stream.expect(TokenTypes.EXCEPT, 'Expected "except"');
+        let compareMethod = policyCompareMethod;
+        // optional: "all" / "any"
+        if (this.stream.check(TokenTypes.ALL) || this.stream.check(TokenTypes.ANY)) {
+            const compareToken = this.stream.next();
+            compareMethod = compareToken.type === TokenTypes.ALL ? AbilityCompare.and : AbilityCompare.or;
+            if (this.stream.check(TokenTypes.OF)) {
+                this.stream.next();
+            }
+            this.stream.expect(TokenTypes.COLON, 'Expected ":" after except group');
+        }
+        else {
+            // implicit except group — no "all/any of:"
+            // but still must end with colon
+            this.stream.expect(TokenTypes.COLON, 'Expected ":" after "except"');
+        }
+        const group = new AbilityRuleSet({
+            id: annotations.id?.value || null,
+            compareMethod,
+            name: annotations.name?.value || null,
+            description: annotations.description?.value || null,
+            isExcept: true,
+            disabled: annotations.disabled?.value ?? undefined,
+        });
+        // read rules
+        while (!this.stream.eof()) {
+            this.consumeLeadingComments();
+            this.consumeLeadingAnnotations();
+            if (this.isStartOfGroup() || this.isStartOfPolicy() || this.isStartOfExcept()) {
+                break;
+            }
+            if (this.stream.check(TokenTypes.IDENTIFIER)) {
                 group.addRule(this.parseRule());
             }
             else {
-                this.syntaxError(`Unexpected token in group: ${this.peek().code}`, this.peek());
+                this.stream.syntaxError(`Unexpected token in except group: ${this.stream.peek().type}`, this.stream.peek());
             }
         }
         return group;
@@ -1687,57 +2448,54 @@ class AbilityDSLParser {
      */
     parseRule() {
         this.consumeLeadingComments();
-        const meta = this.takeAnnotations();
-        // if (this.check(AbilityDSLToken.ALWAYS) || this.check(AbilityDSLToken.NEVER)) {
-        //   // Checking that there are no extra tokens after the value
-        //   // (skip comments)
-        //   this.consumeLeadingComments();
-        //   const specOperator = this.consume();
-        //   // return new AbilityRule({
-        //   //   subject: '',
-        //   //   resource,
-        //   //   condition,
-        //   //   name: meta.name,
-        //   // });
-        // }
-        const isNeverAlways = this.check(AbilityDSLToken.ALWAYS) || this.check(AbilityDSLToken.NEVER);
-        if (!isNeverAlways && !this.check(AbilityDSLToken.IDENTIFIER)) {
-            this.syntaxError(`Expected identifier, but got ${this.peek().code}`, this.peek());
-        }
-        // Subject (e.g., "user.roles")
+        this.consumeLeadingAnnotations();
+        const annotations = this.takeAnnotations('rule');
+        const isNeverAlways = this.stream.check(TokenTypes.ALWAYS) || this.stream.check(TokenTypes.NEVER);
+        if (!isNeverAlways && !this.stream.check(TokenTypes.IDENTIFIER)) {
+            this.stream.syntaxError(`Expected identifier, but got ${this.stream.peek().type}`, this.stream.peek());
+        }
+        // subject
         const subject = isNeverAlways
             ? ''
-            : this.consume(AbilityDSLToken.IDENTIFIER, 'Expected field').value;
-        // Operator (e.g., "contains", "equals", "is not null")
-        const { condition, operator } = this.parseConditionOperator();
-        let resource;
-        let beforePos = this.pos;
-        // Special operators that don't consume a value token.
-        if (operator === AbilityDSLToken.EQ_NULL ||
-            operator === AbilityDSLToken.NOT_EQ_NULL ||
-            operator === AbilityDSLToken.NULL ||
-            operator === AbilityDSLToken.ALWAYS ||
-            operator === AbilityDSLToken.NEVER) {
-            resource = null;
+            : this.stream.expect(TokenTypes.IDENTIFIER, 'Expected field').value;
+        // check alias
+        if (this.aliasBuffer.has(subject)) {
+            return this.aliasBuffer.get(subject);
         }
-        else {
-            beforePos = this.pos;
+        // operator
+        const { condition, operator } = this.parseConditionOperator();
+        // value
+        let resource = null;
+        let valueToken = null;
+        const operatorConsumesValue = operator !== TokenTypes.EQ_NULL &&
+            operator !== TokenTypes.NOT_EQ_NULL &&
+            operator !== TokenTypes.NULL &&
+            operator !== TokenTypes.ALWAYS &&
+            operator !== TokenTypes.NEVER;
+        if (operatorConsumesValue) {
+            this.stream.mark();
             resource = this.parseValue();
+            valueToken = this.stream.lookPrev();
+            this.stream.commit();
         }
-        // Checking that there are no extra tokens after the value
-        // (skip comments)
         this.consumeLeadingComments();
-        const resourceToken = this.tokens[beforePos];
+        this.consumeLeadingAnnotations();
+        this.consumeLeadingAliases();
+        // validation: identifier without dot → error
         if (typeof resource === 'string' &&
-            resourceToken.code === AbilityDSLToken.IDENTIFIER &&
-            !resourceToken.value.includes('.')) {
-            this.syntaxError(`Expected comparison operator or value, got \`${resource}\``, this.tokens[beforePos], [AbilityDSLToken.KEYWORD]);
+            valueToken &&
+            valueToken.type === TokenTypes.IDENTIFIER &&
+            !valueToken.value.includes('.')) {
+            this.stream.syntaxError(`Expected comparison operator or value, got \`${resource}\``, valueToken, [TokenTypes.KEYWORD]);
         }
         return new AbilityRule({
+            id: annotations.id?.value || null,
             subject,
             resource,
             condition,
-            name: meta.name,
+            name: annotations.name?.value || null,
+            description: annotations.description?.value || null,
+            disabled: annotations.disabled?.value ?? undefined,
         });
     }
     // -------------------------------------------------------------------------
@@ -1748,200 +2506,241 @@ class AbilityDSLParser {
      * Returns both the resulting AbilityCondition and the token type that was consumed.
      */
     parseConditionOperator() {
-        const savedPos = this.pos;
         // "always"
+        this.stream.mark();
         if (this.matchWord('always')) {
-            return { condition: AbilityCondition.always, operator: AbilityDSLToken.ALWAYS };
+            this.stream.commit();
+            return { condition: AbilityCondition.always, operator: TokenTypes.ALWAYS };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "never"
+        this.stream.mark();
         if (this.matchWord('never')) {
-            return { condition: AbilityCondition.never, operator: AbilityDSLToken.NEVER };
+            this.stream.commit();
+            return { condition: AbilityCondition.never, operator: TokenTypes.NEVER };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length equals"
+        this.stream.mark();
         if (this.matchWord('length') && this.matchWord('equals')) {
-            return { condition: AbilityCondition.length_equals, operator: AbilityDSLToken.LEN_EQ };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_equals, operator: TokenTypes.LEN_EQ };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length ="
+        this.stream.mark();
         if (this.matchWord('length') && this.matchSymbol('=')) {
-            return { condition: AbilityCondition.length_equals, operator: AbilityDSLToken.LEN_EQ };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_equals, operator: TokenTypes.LEN_EQ };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length greater than"
+        this.stream.mark();
         if (this.matchWord('length') && this.matchWord('greater') && this.matchWord('than')) {
-            return { condition: AbilityCondition.length_greater_than, operator: AbilityDSLToken.LEN_GT };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_greater_than, operator: TokenTypes.LEN_GT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length >"
+        this.stream.mark();
         if (this.matchWord('length') && this.matchSymbol('>')) {
-            return { condition: AbilityCondition.length_greater_than, operator: AbilityDSLToken.LEN_GT };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_greater_than, operator: TokenTypes.LEN_GT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length less than"
+        this.stream.mark();
         if (this.matchWord('length') && this.matchWord('less') && this.matchWord('than')) {
-            return { condition: AbilityCondition.length_less_than, operator: AbilityDSLToken.LEN_LT };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_less_than, operator: TokenTypes.LEN_LT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "length <"
+        this.stream.mark();
         if (this.matchWord('length') && this.matchSymbol('<')) {
-            return { condition: AbilityCondition.length_less_than, operator: AbilityDSLToken.LEN_LT };
+            this.stream.commit();
+            return { condition: AbilityCondition.length_less_than, operator: TokenTypes.LEN_LT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "greater than or equal"
+        this.stream.mark();
         if (this.matchWord('greater') &&
             this.matchWord('than') &&
             this.matchWord('or') &&
             this.matchWord('equal')) {
-            return { condition: AbilityCondition.greater_or_equal, operator: AbilityDSLToken.GTE };
+            this.stream.commit();
+            return { condition: AbilityCondition.greater_or_equal, operator: TokenTypes.GTE };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // greater than
+        this.stream.mark();
         if (this.matchWord('greater') && this.matchWord('than')) {
-            return { condition: AbilityCondition.greater_than, operator: AbilityDSLToken.GT };
+            this.stream.commit();
+            return { condition: AbilityCondition.greater_than, operator: TokenTypes.GT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // less than or equal
+        this.stream.mark();
         if (this.matchWord('less') &&
             this.matchWord('than') &&
             this.matchWord('or') &&
             this.matchWord('equal')) {
-            return { condition: AbilityCondition.less_or_equal, operator: AbilityDSLToken.LTE };
+            this.stream.commit();
+            return { condition: AbilityCondition.less_or_equal, operator: TokenTypes.LTE };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // less than
         if (this.matchWord('less') && this.matchWord('than')) {
-            return { condition: AbilityCondition.less_than, operator: AbilityDSLToken.LT };
+            return { condition: AbilityCondition.less_than, operator: TokenTypes.LT };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "not contains"
+        this.stream.mark();
         if (this.matchWord('not') && this.matchWord('contains')) {
+            this.stream.commit();
             return {
                 condition: AbilityCondition.not_contains,
-                operator: AbilityDSLToken.NOT_CONTAINS,
+                operator: TokenTypes.NOT_CONTAINS,
             };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "not includes"
+        this.stream.mark();
         if (this.matchWord('not') && this.matchWord('includes')) {
+            this.stream.commit();
             return {
                 condition: AbilityCondition.not_contains,
-                operator: AbilityDSLToken.NOT_CONTAINS,
+                operator: TokenTypes.NOT_CONTAINS,
             };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "not includes"
+        this.stream.mark();
         if (this.matchWord('not') && this.matchWord('has')) {
+            this.stream.commit();
             return {
                 condition: AbilityCondition.not_contains,
-                operator: AbilityDSLToken.NOT_CONTAINS,
+                operator: TokenTypes.NOT_CONTAINS,
             };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // "is equals"
+        this.stream.mark();
         if (this.matchWord('is') && this.matchWord('equals')) {
-            return { condition: AbilityCondition.equals, operator: AbilityDSLToken.EQ };
+            this.stream.commit();
+            return { condition: AbilityCondition.equals, operator: TokenTypes.EQ };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // not equal
+        this.stream.mark();
         if (this.matchWord('not') && this.matchWord('equals')) {
-            return { condition: AbilityCondition.not_equals, operator: AbilityDSLToken.NOT_EQ };
+            this.stream.commit();
+            return { condition: AbilityCondition.not_equals, operator: TokenTypes.NOT_EQ };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // is not equals
+        this.stream.mark();
         if (this.matchWord('is') && this.matchWord('not') && this.matchWord('equals')) {
-            return { condition: AbilityCondition.not_equals, operator: AbilityDSLToken.NOT_EQ };
+            this.stream.commit();
+            return { condition: AbilityCondition.not_equals, operator: TokenTypes.NOT_EQ };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // is in
+        this.stream.mark();
         if (this.matchWord('is') && this.matchWord('in')) {
-            return { condition: AbilityCondition.in, operator: AbilityDSLToken.IN };
+            this.stream.commit();
+            return { condition: AbilityCondition.in, operator: TokenTypes.IN };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // not in
+        this.stream.mark();
         if (this.matchWord('not') && this.matchWord('in')) {
-            return { condition: AbilityCondition.not_in, operator: AbilityDSLToken.NOT_IN };
+            this.stream.commit();
+            return { condition: AbilityCondition.not_in, operator: TokenTypes.NOT_IN };
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // is not null
+        this.stream.mark();
         if (this.matchWord('is') && this.matchWord('not')) {
-            if (this.check(AbilityDSLToken.NULL)) {
-                this.advance();
+            if (this.stream.check(TokenTypes.NULL)) {
+                this.stream.next();
+                this.stream.commit();
                 return {
                     condition: AbilityCondition.not_equals,
-                    operator: AbilityDSLToken.NOT_EQ_NULL,
+                    operator: TokenTypes.NOT_EQ_NULL,
                 };
             }
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // is null
+        this.stream.mark();
         if (this.matchWord('is') && this.matchWord('null')) {
-            if (this.check(AbilityDSLToken.NULL)) {
-                this.advance();
+            if (this.stream.check(TokenTypes.NULL)) {
+                this.stream.commit();
+                this.stream.next();
                 return {
                     condition: AbilityCondition.equals,
-                    operator: AbilityDSLToken.EQ_NULL,
+                    operator: TokenTypes.EQ_NULL,
                 };
             }
         }
-        this.pos = savedPos;
+        this.stream.reset();
         // Single token (symbol or keyword)
-        const token = this.peek();
-        if (token.code !== AbilityDSLToken.SYMBOL &&
-            token.code !== AbilityDSLToken.KEYWORD &&
-            token.code !== AbilityDSLToken.NULL) {
-            this.syntaxError(`Expected comparison operator, got \`${token.value}\``, token, [
-                AbilityDSLToken.SYMBOL,
-                AbilityDSLToken.KEYWORD,
-                AbilityDSLToken.NULL,
+        const token = this.stream.peek();
+        if (token.type !== TokenTypes.SYMBOL &&
+            token.type !== TokenTypes.KEYWORD &&
+            token.type !== TokenTypes.NULL) {
+            this.stream.syntaxError(`Expected comparison operator, got \`${token.value}\``, token, [
+                TokenTypes.SYMBOL,
+                TokenTypes.KEYWORD,
+                TokenTypes.NULL,
             ]);
         }
-        this.advance();
-        switch (token.code) {
-            case AbilityDSLToken.SYMBOL:
+        this.stream.next();
+        switch (token.type) {
+            case TokenTypes.SYMBOL:
                 if (token.value === '=' || token.value === '==')
-                    return { condition: AbilityCondition.equals, operator: AbilityDSLToken.EQ };
+                    return { condition: AbilityCondition.equals, operator: TokenTypes.EQ };
                 if (token.value === '!=' || token.value === '<>')
-                    return { condition: AbilityCondition.not_equals, operator: AbilityDSLToken.NOT_EQ };
+                    return { condition: AbilityCondition.not_equals, operator: TokenTypes.NOT_EQ };
                 if (token.value === '>')
-                    return { condition: AbilityCondition.greater_than, operator: AbilityDSLToken.GT };
+                    return { condition: AbilityCondition.greater_than, operator: TokenTypes.GT };
                 if (token.value === '<')
-                    return { condition: AbilityCondition.less_than, operator: AbilityDSLToken.LT };
+                    return { condition: AbilityCondition.less_than, operator: TokenTypes.LT };
                 if (token.value === '>=')
-                    return { condition: AbilityCondition.greater_or_equal, operator: AbilityDSLToken.GTE };
+                    return { condition: AbilityCondition.greater_or_equal, operator: TokenTypes.GTE };
                 if (token.value === '<=')
-                    return { condition: AbilityCondition.less_or_equal, operator: AbilityDSLToken.LTE };
+                    return { condition: AbilityCondition.less_or_equal, operator: TokenTypes.LTE };
                 break;
-            case AbilityDSLToken.KEYWORD:
+            case TokenTypes.KEYWORD:
                 if (token.value === 'contains' || token.value === 'includes' || token.value === 'has')
-                    return { condition: AbilityCondition.contains, operator: AbilityDSLToken.CONTAINS };
+                    return { condition: AbilityCondition.contains, operator: TokenTypes.CONTAINS };
                 if (token.value === 'in')
-                    return { condition: AbilityCondition.in, operator: AbilityDSLToken.IN };
+                    return { condition: AbilityCondition.in, operator: TokenTypes.IN };
                 if (token.value === 'equals')
-                    return { condition: AbilityCondition.equals, operator: AbilityDSLToken.EQ };
+                    return { condition: AbilityCondition.equals, operator: TokenTypes.EQ };
                 if (token.value === 'gte') {
-                    return { condition: AbilityCondition.greater_or_equal, operator: AbilityDSLToken.GTE };
+                    return { condition: AbilityCondition.greater_or_equal, operator: TokenTypes.GTE };
                 }
                 if (token.value === 'greater' || token.value === 'gt') {
                     // If we come here, it means "greater" without "than" – treat as '>'
-                    return { condition: AbilityCondition.greater_than, operator: AbilityDSLToken.GT };
+                    return { condition: AbilityCondition.greater_than, operator: TokenTypes.GT };
                 }
                 if (token.value === 'less' || token.value === 'lt') {
-                    return { condition: AbilityCondition.less_than, operator: AbilityDSLToken.LT };
+                    return { condition: AbilityCondition.less_than, operator: TokenTypes.LT };
                 }
                 if (token.value === 'lte') {
-                    return { condition: AbilityCondition.less_or_equal, operator: AbilityDSLToken.LTE };
+                    return { condition: AbilityCondition.less_or_equal, operator: TokenTypes.LTE };
                 }
                 if (token.value === 'is') {
                     // "is" alone -> equals
-                    return { condition: AbilityCondition.equals, operator: AbilityDSLToken.EQ };
+                    return { condition: AbilityCondition.equals, operator: TokenTypes.EQ };
                 }
                 break;
         }
-        return this.syntaxError(`Unexpected operator token \`${token.value}\``, token, [
-            AbilityDSLToken.SYMBOL,
-            AbilityDSLToken.KEYWORD,
+        return this.stream.syntaxError(`Unexpected operator token \`${token.value}\``, token, [
+            TokenTypes.SYMBOL,
+            TokenTypes.KEYWORD,
         ]);
     }
     /**
@@ -1950,26 +2749,26 @@ class AbilityDSLParser {
      * @returns True if the next token has that value.
      */
     matchWord(word) {
-        if (this.isAtEnd()) {
+        if (this.stream.eof()) {
             return false;
         }
-        const token = this.peek();
-        if ((token.code === AbilityDSLToken.KEYWORD ||
-            token.code === AbilityDSLToken.IDENTIFIER ||
-            token.code === AbilityDSLToken.ALWAYS ||
-            token.code === AbilityDSLToken.NEVER) &&
+        const token = this.stream.peek();
+        if ((token.type === TokenTypes.KEYWORD ||
+            token.type === TokenTypes.IDENTIFIER ||
+            token.type === TokenTypes.ALWAYS ||
+            token.type === TokenTypes.NEVER) &&
             token.value === word) {
-            this.advance();
+            this.stream.next();
             return true;
         }
         return false;
     }
     matchSymbol(symbol) {
-        if (this.isAtEnd())
+        if (this.stream.eof())
             return false;
-        const token = this.peek();
-        if (token.code === AbilityDSLToken.SYMBOL && token.value === symbol) {
-            this.advance();
+        const token = this.stream.peek();
+        if (token.type === TokenTypes.SYMBOL && token.value === symbol) {
+            this.stream.next();
             return true;
         }
         return false;
@@ -1983,32 +2782,34 @@ class AbilityDSLParser {
      */
     parseValue() {
         // Arrays start with a left bracket
-        if (this.check(AbilityDSLToken.LBRACKET)) {
-            this.advance();
+        if (this.stream.check(TokenTypes.LBRACKET)) {
+            this.stream.next();
             return this.parseArray();
         }
         // Ensure we are not about to read a structural token as a value.
-        const token = this.peek();
-        if (token.code === AbilityDSLToken.ALL ||
-            token.code === AbilityDSLToken.ANY ||
-            token.code === AbilityDSLToken.EFFECT) {
-            this.syntaxError(`Unexpected ${token.code} in value position`, token);
+        const token = this.stream.peek();
+        if (token.type === TokenTypes.ALL ||
+            token.type === TokenTypes.ANY ||
+            token.type === TokenTypes.EFFECT) {
+            this.stream.syntaxError(`Unexpected ${token.type} in value position`, token);
         }
-        this.advance();
+        this.stream.next();
         // CHECK THIS SWITCH COMPARE
-        switch (token.code) {
-            case AbilityDSLToken.STRING:
+        switch (token.type) {
+            case TokenTypes.STRING:
                 return token.value;
-            case AbilityDSLToken.NUMBER:
+            case TokenTypes.NUMBER:
                 return Number(token.value);
-            case AbilityDSLToken.BOOLEAN:
+            case TokenTypes.BOOLEAN:
                 return token.value === 'true';
-            case AbilityDSLToken.NULL:
+            case TokenTypes.NULL:
                 return null;
-            case AbilityDSLToken.IDENTIFIER:
+            case TokenTypes.IDENTIFIER:
                 return token.value;
             default: {
-                this.syntaxError(`Unexpected value token "${token.value}"`, token ?? this.tokens[this.tokens.length - 1], [AbilityDSLToken.KEYWORD]);
+                this.stream.syntaxError(`Unexpected value token "${token.value}"`, token, [
+                    TokenTypes.KEYWORD,
+                ]);
             }
         }
     }
@@ -2019,11 +2820,11 @@ class AbilityDSLParser {
     parseArray() {
         const arr = [];
         // Handle empty array
-        if (this.check(AbilityDSLToken.RBRACKET)) {
-            this.advance();
+        if (this.stream.check(TokenTypes.RBRACKET)) {
+            this.stream.next();
             return arr;
         }
-        while (!this.isAtEnd() && !this.check(AbilityDSLToken.RBRACKET)) {
+        while (!this.stream.eof() && !this.stream.check(TokenTypes.RBRACKET)) {
             const value = this.parseValue();
             // Flatten nested arrays if they appear (though grammar doesn't currently allow nesting).
             if (Array.isArray(value)) {
@@ -2036,155 +2837,359 @@ class AbilityDSLParser {
             }
             else if (value === null) {
                 // Null is allowed in arrays? Currently, we throw.
-                this.syntaxError('Unexpected null in array', this.peek());
+                this.stream.syntaxError('Unexpected null in array', this.stream.peek());
             }
             // Optional comma between elements
-            if (this.check(AbilityDSLToken.COMMA)) {
-                this.advance();
+            if (this.stream.check(TokenTypes.COMMA)) {
+                this.stream.next();
             }
         }
-        this.consume(AbilityDSLToken.RBRACKET, 'Expected "]"');
+        this.stream.expect(TokenTypes.RBRACKET, 'Expected "]"');
         return arr;
     }
     // -------------------------------------------------------------------------
-    // #region Annotations and comments
+    // #region comments
     // -------------------------------------------------------------------------
     consumeLeadingComments() {
-        while (this.check(AbilityDSLToken.COMMENT)) {
-            const token = this.advance();
-            this.processCommentToken(token);
-        }
-    }
-    processCommentToken(token) {
-        const text = token.value.trim();
-        if (text.startsWith('@name ')) {
-            this.annotationBuffer.name = text.slice(6).trim();
-        }
-        if (text.startsWith('@description ')) {
-            this.annotationBuffer.description = text.slice(13).trim();
-        }
-    }
-    takeAnnotations() {
-        const meta = { ...this.annotationBuffer };
-        this.annotationBuffer = {
-            name: null,
-            description: null,
-        };
-        return meta;
-    }
-    // -------------------------------------------------------------------------
-    // #region Errors
-    // -------------------------------------------------------------------------
-    syntaxError(details, token, expected) {
-        const lines = this.dsl.split(/\r?\n/);
-        const lineIdx = token.line - 1;
-        const lineBefore = lineIdx > 0 ? lines[lineIdx - 1] : '';
-        const current = lines[lineIdx];
-        const linesAfter = lineIdx + 1 < lines.length ? lines[lineIdx + 1] : '';
-        const wave = ' '.repeat(Math.max(0, token.column - 1)) + '~'.repeat(token.value.length);
-        const lineNumWidth = String(token.line + 1).length;
-        const num = (n) => String(n).padStart(lineNumWidth, ' ');
-        let context = '';
-        if (lineBefore.trim() !== '') {
-            context += `${num(token.line - 1)} | ${lineBefore}\n`;
-        }
-        context += `${num(token.line)} | ${current}\n`;
-        context += `${' '.repeat(lineNumWidth)} | ${wave}\n`;
-        if (linesAfter.trim() !== '') {
-            context += `${num(token.line + 1)} | ${linesAfter}`;
-        }
-        let finalDetails = details;
-        if (expected && expected?.length > 0) {
-            const actual = token.value;
-            const suggestion = this.suggest(actual, expected);
-            const detailsMsg = `${details}\nDetails: Unexpected value token \`${actual}\``;
-            finalDetails = suggestion ? `${detailsMsg} Did you mean \`${suggestion}\`?` : detailsMsg;
+        while (this.stream.check(TokenTypes.COMMENT)) {
+            this.stream.next();
+            // this.processCommentToken(token);
+        }
+    }
+    // private _consumeLeadingAnnotations() {
+    //   while (this.stream.check(TokenTypes.ANNOTATION)) {
+    //     const token = this.stream.next();
+    //     this.processAnnotationToken(token);
+    //   }
+    // }
+    consumeLeadingAliases() {
+        while (this.stream.check(TokenTypes.ALIAS)) {
+            this.stream.next(); // consume "alias"
+            const nameToken = this.stream.expect(TokenTypes.IDENTIFIER, `Expected alias name`);
+            const aliasKey = nameToken.value;
+            this.stream.expect(TokenTypes.COLON, `Expected colon after an alias`);
+            const annotations = this.takeAnnotations('alias');
+            while (!this.stream.eof() && !this.isStartOfAlias() && !this.isStartOfPolicy()) {
+                const rule = this.parseRule();
+                rule.name = annotations.get('name')?.value || aliasKey;
+                rule.description = annotations.get('description')?.value;
+                if (annotations.get('disabled')?.value === true) {
+                    rule.disabled = true;
+                }
+                this.aliasBuffer.set(aliasKey, rule);
+            }
         }
-        throw new AbilityDSLSyntaxError(token.line, token.column, context + '\n', finalDetails);
     }
-    suggest(actual, expectedTypes) {
-        const candidates = [];
-        for (const type of expectedTypes) {
-            candidates.push(type);
-        }
-        const uniqueCandidates = [...new Set(candidates)];
-        let best = null;
-        let bestDist = 3;
-        for (const candidate of uniqueCandidates) {
-            const d = this.levenshteinDistance(actual.toLowerCase(), candidate.toLowerCase());
-            if (d < bestDist) {
-                bestDist = d;
-                best = candidate;
+    consumeLeadingAnnotations() {
+        while (this.stream.check(TokenTypes.ANNOTATION)) {
+            const token = this.stream.next();
+            const text = token.value.trim();
+            if (text.startsWith('@id ')) {
+                this.annBuffer.setID(text.slice(4).trim(), token);
+            }
+            if (text.startsWith('@name ')) {
+                this.annBuffer.setName(text.slice(6).trim(), token);
+            }
+            if (text.startsWith('@description ')) {
+                this.annBuffer.setDescription(text.slice(13).trim(), token);
+            }
+            if (text.startsWith('@priority ')) {
+                this.annBuffer.setPriority(parseInt(text.slice(10).trim(), 10), token);
+            }
+            if (text.startsWith('@disabled')) {
+                const value = text.slice(9).trim();
+                this.annBuffer.setDisabled(value.length === 0 ? true : text.slice(9).trim() === 'true', token);
+            }
+            if (text.startsWith('@tags ')) {
+                const value = text
+                    .slice(6)
+                    .trim()
+                    .split(',')
+                    .map(tag => tag.trim());
+                this.annBuffer.setTags(value, token);
             }
         }
-        return best;
     }
-    levenshteinDistance(a, b) {
-        const matrix = Array.from({ length: b.length + 1 }, () => Array.from({ length: a.length + 1 }, () => 0));
-        for (let i = 0; i <= a.length; i++)
-            matrix[0][i] = i;
-        for (let j = 0; j <= b.length; j++)
-            matrix[j][0] = j;
-        for (let j = 1; j <= b.length; j++) {
-            for (let i = 1; i <= a.length; i++) {
-                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-                matrix[j][i] = Math.min(matrix[j][i - 1] + 1, matrix[j - 1][i] + 1, matrix[j - 1][i - 1] + cost);
+    takeAnnotations(owner) {
+        const ann = this.annBuffer.clone();
+        this.annBuffer.clear();
+        const allowed = AnnotationAllowed[owner];
+        for (const key of Object.keys(ann['store'])) {
+            const entry = ann.get(key);
+            if (!entry)
+                continue;
+            if (!allowed.has(key)) {
+                this.stream.syntaxError(`Annotation @${key} is not allowed on ${owner}. Allowed: ${[...allowed]
+                    .map(a => '@' + a)
+                    .join(', ')}`, entry.token ?? this.stream.peek());
             }
         }
-        return matrix[b.length][a.length];
+        return ann;
     }
     // -------------------------------------------------------------------------
-    // #region Helper / lookahead methods
+    // #region Helpers
     // -------------------------------------------------------------------------
-    consumeOneOf(types, message) {
-        const token = this.peek();
-        for (const t of types) {
-            if (token && token.code === t) {
-                return this.advance();
-            }
-        }
-        const expected = types.map(t => t).join(', ');
-        const actual = token ? token.value : AbilityDSLToken.EOF;
-        const suggestion = this.suggest(actual, types);
-        const details = `${message}\nDetails: Unexpected token \`${actual}\`, expected one of: ${expected}.`;
-        const finalMsg = suggestion ? `${details} Did you mean \`${suggestion}\`?` : details;
-        this.syntaxError(finalMsg, token ?? this.tokens[this.tokens.length - 1]);
+    isStartOfPolicy() {
+        return this.stream.check(TokenTypes.EFFECT);
     }
-    consume(type, message) {
-        const token = this.peek();
-        if (token && token.code === type) {
-            return this.advance();
+    isStartOfGroup() {
+        return this.stream.check(TokenTypes.ALL) || this.stream.check(TokenTypes.ANY);
+    }
+    isStartOfExcept() {
+        return this.stream.check(TokenTypes.EXCEPT);
+    }
+    isStartOfAlias() {
+        return this.stream.check(TokenTypes.ALIAS);
+    }
+}
+
+function ability(strings, ...expr) {
+    const dsl = strings.reduce((acc, s, i) => acc + s + (expr[i] ?? ''), '');
+    return new AbilityDSLParser(dsl).parse();
+}
+
+class AbilityStrategy {
+    policies;
+    matched;
+    constructor(policies) {
+        this.policies = policies;
+        this.matched = policies.filter(p => p.matchState === AbilityMatch.match);
+    }
+    matchedPolicies() {
+        return this.matched;
+    }
+    firstMatched() {
+        return this.matched[0] ?? null;
+    }
+    lastMatched() {
+        return this.matched.length > 0 ? this.matched[this.matched.length - 1] : null;
+    }
+    hasPermit() {
+        return this.matched.some(p => p.effect === AbilityPolicyEffect.permit);
+    }
+    hasDeny() {
+        return this.matched.some(p => p.effect === AbilityPolicyEffect.deny);
+    }
+    isAllowed() {
+        return this.evaluate() === AbilityPolicyEffect.permit;
+    }
+    isDenied() {
+        return this.evaluate() === AbilityPolicyEffect.deny;
+    }
+}
+
+/**
+ * AllMustPermitStrategy
+ *
+ * This strategy requires *every applicable policy* to return "permit".
+ * If at least one policy returns "deny" or "not applicable", the final result is "deny".
+ *
+ * Use this strategy when:
+ * - You want strict, conservative access control.
+ * - All rules must explicitly allow the action.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: deny (because not all policies permitted)
+ */
+class AllMustPermitStrategy extends AbilityStrategy {
+    evaluate() {
+        const matched = this.matchedPolicies();
+        if (matched.length === 0) {
+            return AbilityPolicyEffect.deny;
         }
-        const expected = type;
-        const actual = token ? token.value : AbilityDSLToken.EOF;
-        const suggestion = this.suggest(actual, [type]);
-        const details = `${message}\nDetails: Unexpected token \`${actual}\`, expected "${expected}".`;
-        const finalMsg = suggestion ? `${details} Did you mean \`${suggestion}\`?` : details;
-        this.syntaxError(finalMsg, token ?? this.tokens[this.tokens.length - 1]);
+        const allPermit = matched.every(p => p.effect === AbilityPolicyEffect.permit);
+        return allPermit ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny;
     }
-    check(type) {
-        if (this.isAtEnd())
-            return false;
-        return this.peek().code === type;
+}
+
+/**
+ * AnyPermitStrategy
+ *
+ * This strategy returns "permit" as soon as *any* applicable policy permits the action.
+ * If no policy permits, the result is "deny".
+ *
+ * Use this strategy when:
+ * - You want optimistic access control.
+ * - A single positive rule should be enough to grant access.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → deny
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (because at least one policy permitted)
+ */
+class AnyPermitStrategy extends AbilityStrategy {
+    evaluate() {
+        return this.hasPermit() ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny;
     }
-    isStartOfPolicy() {
-        return this.check(AbilityDSLToken.EFFECT);
+}
+
+/**
+ * DenyOverridesStrategy
+ *
+ * This strategy gives absolute priority to "deny".
+ * If any applicable policy returns "deny", the final result is "deny".
+ * Otherwise, if at least one policy permits, the result is "permit".
+ *
+ * Use this strategy when:
+ * - Security is critical.
+ * - A single denial must block access.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → deny
+ *     P3 → permit
+ *   Result: deny (because deny overrides everything)
+ */
+class DenyOverridesStrategy extends AbilityStrategy {
+    evaluate() {
+        if (this.hasDeny()) {
+            return AbilityPolicyEffect.deny;
+        }
+        if (this.hasPermit()) {
+            return AbilityPolicyEffect.permit;
+        }
+        return AbilityPolicyEffect.deny;
     }
-    isStartOfGroup() {
-        return this.check(AbilityDSLToken.ALL) || this.check(AbilityDSLToken.ANY);
+}
+
+/**
+ * FirstMatchStrategy
+ *
+ * This strategy evaluates policies in order and returns the result of the *first applicable* policy.
+ * Remaining policies are ignored.
+ *
+ * Use this strategy when:
+ * - Policy order matters.
+ * - You want predictable, sequential rule evaluation.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → not applicable
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (P2 is the first applicable)
+ */
+class FirstMatchStrategy extends AbilityStrategy {
+    evaluate() {
+        const first = this.firstMatched();
+        return first?.effect ?? AbilityPolicyEffect.deny;
     }
-    advance() {
-        return this.tokens[this.pos++];
+}
+
+/**
+ * OnlyOneApplicableStrategy
+ *
+ * This strategy requires that *exactly one* policy is applicable.
+ * If zero or more than one policy applies, the result is "deny".
+ *
+ * Use this strategy when:
+ * - Policies must be mutually exclusive.
+ * - You want to detect ambiguous or conflicting rules.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → applicable
+ *     P2 → applicable
+ *   Result: deny (more than one applicable policy)
+ */
+class OnlyOneApplicableStrategy extends AbilityStrategy {
+    evaluate() {
+        const matched = this.matchedPolicies();
+        if (matched.length === 1) {
+            return matched[0].effect;
+        }
+        return AbilityPolicyEffect.deny;
     }
-    peek() {
-        return this.tokens[this.pos];
+}
+
+/**
+ * PermitOverridesStrategy
+ *
+ * This strategy gives priority to "permit".
+ * If any applicable policy permits, the final result is "permit".
+ * Deny is returned only if no policy permits.
+ *
+ * Use this strategy when:
+ * - You want permissive behavior.
+ * - A single positive rule should override denials.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → deny
+ *     P2 → permit
+ *     P3 → deny
+ *   Result: permit (permit overrides deny)
+ */
+class PermitOverridesStrategy extends AbilityStrategy {
+    evaluate() {
+        if (this.hasPermit()) {
+            return AbilityPolicyEffect.permit;
+        }
+        if (this.hasDeny()) {
+            return AbilityPolicyEffect.deny;
+        }
+        return AbilityPolicyEffect.deny;
     }
-    isAtEnd() {
-        return this.peek().code === AbilityDSLToken.EOF;
+}
+
+/**
+ * SequentialLastMatchStrategy
+ *
+ * This strategy evaluates all applicable policies in order and returns the result of the *last* applicable one.
+ *
+ * Use this strategy when:
+ * - Later policies should override earlier ones.
+ * - You want a "last rule wins" behavior.
+ *
+ * Example:
+ *   Policies:
+ *     P1 → permit
+ *     P2 → deny
+ *     P3 → permit
+ *   Result: permit (P3 is the last applicable)
+ */
+class SequentialLastMatchStrategy extends AbilityStrategy {
+    evaluate() {
+        const last = this.lastMatched();
+        return last?.effect ?? AbilityPolicyEffect.deny;
+    }
+}
+
+/**
+ * PriorityStrategy
+ *
+ * This strategy evaluates policies based on their numeric priority.
+ * The policy with the highest priority (lowest number or highest number depending on implementation)
+ * determines the final result.
+ *
+ * Use this strategy when:
+ * - Policies have explicit priority levels.
+ * - You want deterministic resolution based on ranking.
+ *
+ * Example:
+ *   Policies:
+ *     P1 (priority 10) → deny
+ *     P2 (priority 1)  → permit
+ *   Result: permit (P2 has higher priority)
+ */
+class PriorityStrategy extends AbilityStrategy {
+    evaluate() {
+        const matched = this.matchedPolicies();
+        if (matched.length === 0) {
+            return AbilityPolicyEffect.deny;
+        }
+        const sorted = [...matched].sort((a, b) => b.priority - a.priority);
+        return sorted[0].effect;
     }
 }
 
-exports.AbilityCode = AbilityCode;
 exports.AbilityCompare = AbilityCompare;
 exports.AbilityCondition = AbilityCondition;
 exports.AbilityDSLLexer = AbilityDSLLexer;
@@ -2202,7 +3207,21 @@ exports.AbilityPolicy = AbilityPolicy;
 exports.AbilityPolicyEffect = AbilityPolicyEffect;
 exports.AbilityResolver = AbilityResolver;
 exports.AbilityResult = AbilityResult;
-exports.AbilityResultState = AbilityResultState;
 exports.AbilityRule = AbilityRule;
 exports.AbilityRuleSet = AbilityRuleSet;
+exports.AbilityStrategy = AbilityStrategy;
 exports.AbilityTypeGenerator = AbilityTypeGenerator;
+exports.AllMustPermitStrategy = AllMustPermitStrategy;
+exports.AnyPermitStrategy = AnyPermitStrategy;
+exports.DenyOverridesStrategy = DenyOverridesStrategy;
+exports.FirstMatchStrategy = FirstMatchStrategy;
+exports.OnlyOneApplicableStrategy = OnlyOneApplicableStrategy;
+exports.PermitOverridesStrategy = PermitOverridesStrategy;
+exports.PriorityStrategy = PriorityStrategy;
+exports.SequentialLastMatchStrategy = SequentialLastMatchStrategy;
+exports.TokenTypes = TokenTypes;
+exports.ability = ability;
+exports.fromLiteral = fromLiteral;
+exports.isConditionEqual = isConditionEqual;
+exports.isConditionNotEqual = isConditionNotEqual;
+exports.toLiteral = toLiteral;