@via-profit/ability 3.5.0 → 3.5.1

package/README.md

@@ -1,6 +1,7 @@
-# @via-profit/Ability
+```markdown
+# @via-profit/ability
 
-> A set of services that partially implement the [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control) principle.
+> A set of services partially implementing the [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control) principle.
 > The package allows you to describe rules, combine them into groups, form policies, and apply them to data to determine permissions.
 
 ![npm version](https://img.shields.io/npm/v/%40via-profit/ability)
@@ -11,7 +12,6 @@
 ![issues](https://img.shields.io/github/issues/via-profit/ability)
 ![stars](https://img.shields.io/github/stars/via-profit/ability?style=social)
 
-
 ## Language / Язык
 
 - [🇬🇧 English](/docs/en/README.md)
@@ -19,27 +19,34 @@
 
 ## Purpose
 
-The package is intended as a **lightweight and extremely simple alternative** to heavy access control systems.  
-Without complex configurations, without dependencies — just a minimal set of tools that allows you to describe rules and policies in a maximally simple DSL.
+The package is intended as a **lightweight and extremely simple alternative** to heavy access control systems.
+No complex configurations, no dependencies – just a minimal set of tools that allows you to describe rules and policies in a very simple DSL.
+
+Unlike classic ABAC models, where policies work on the principle *"matched → applied, didn't match → ignored"*, Ability uses a **simplified and more predictable state‑machine model**:
+
+- **all** matching policies are executed in the order they are declared,
+- each policy can **set** a state (`permit` or `deny`),
+- each policy can **reset** the state if its conditions are not met,
+- the final result is determined by the **last processed policy**, not just the one that matched.
 
-## Table of Contents
+## Contents
 
-- [Quick Start](#quick-start)
-- [Fundamentals](#fundamentals)
+- [Quick start](#quick-start)
+- [Key concepts](#key-concepts)
 - [DSL](#dsl)
-- [Combining Policies](#combining-policies)
+- [Combining policies](#combining-policies)
 - [Policy Environment](#policy-environment)
-- [TypeScript Type Generator](#typescript-type-generator)
-- [Policy Debugging](#policy-debugging)
+- [TypeScript type generator](#typescript-type-generator)
+- [Debugging policies](#debugging-policies)
 - [Troubleshooting](#troubleshooting)
-- [Design Recommendations](#design-recommendations)
+- [Design recommendations](#design-recommendations)
 - [Examples](#examples)
 - [Performance](#performance)
-- [API Reference](./api.md)
+- [Api-Reference](./api.md)
 
-## Quick Start
+## Quick start
 
-Install the package, write DSL, call the parser, and run the resolver.
+Install the package, write DSL, call the parser, run the resolver.
 
 ### Installation
 
@@ -55,7 +62,7 @@ yarn add @via-profit/ability
 pnpm add @via-profit/ability
 ```
 
-### Example: Deny access to `passwordHash` for everyone except the owner
+### Example: deny access to `passwordHash` to everyone except the owner
 
 Suppose we have user data:
 
@@ -69,7 +76,7 @@ const user = {
 
 We need to deny reading `passwordHash` to everyone except the user themselves.
 
-#### DSL Policy
+#### DSL policy
 
 In the policy language, this looks like:
 
@@ -80,16 +87,16 @@ deny permission.user.passwordHash if any:
 
 **Explanation:**
 
-- `deny` — policy effect (deny access)
-- `permission.user.passwordHash` — permission key.
-- `if any:` — start of the condition block
-- `viewer.id is not equals owner.id` — rule: if the requester's ID is not equal to the owner's ID
+- `deny` – policy effect (deny access)
+- `permission.user.passwordHash` – permission key.
+- `if any:` – start of conditions block
+- `viewer.id is not equals owner.id` – rule: if the requester's ID does not equal the owner's ID
 
-If `viewer.id` is not equal to `owner.id`, the rule is satisfied and the policy returns `deny` — access denied. If the IDs match (i.e., the user requests their own data), the rule does not trigger, and access is allowed.
+If `viewer.id` does not equal `owner.id`, the rule is considered satisfied, and the policy returns `deny` – access denied. If the IDs match (i.e., the user requests their own data), the rule does not trigger, and access is allowed.
 
-*Note: The permission key is formed according to the principle: `permission.` + your custom key in dot notation. For example, the key `foo.bar.baz` in DSL would be `permission.foo.bar.baz`.*
+_Note: The permission key is formed as `permission.` + your custom key in **dot notation**, e.g., the key `foo.bar.baz` in DSL would be `permission.foo.bar.baz`_
 
-#### Check in Code
+#### Code check
 
 ```ts
 import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
@@ -99,60 +106,77 @@ deny permission.user.passwordHash if any:
   viewer.id is not equals owner.id
 `;
 
-const policies = new AbilityDSLParser(dsl).parse(); // obtain policies
+const policies = new AbilityDSLParser(dsl).parse(); // get policies
 const resolver = new AbilityResolver(policies); // create resolver
 
 resolver.enforce('user.passwordHash', {
   viewer: { id: '1' },
   owner: { id: '2' },
-}); // will throw an error — access denied
+}); // will throw an error – access denied
 ```
-In `enforce`, the key is passed without the `permission.` prefix — it is automatically removed by the parser.
+In `enforce`, the key is passed without the `permission.` prefix – it is automatically removed by the parser.
+
+## Key concepts
+
+Let's list the key points you need to know before starting to use the package:
+
+1. **The resolver (`AbilityResolver`) works on the `Default Deny` principle.**
+   If no policy has set a final state, the result will be `deny`
+   ([see here](#troubleshooting)).
+   To avoid unexpected `deny`, ensure there is at least one `permit` policy that can match.
+   Only then add `deny` policies.
+
+2. **Policies are processed sequentially, from top to bottom.**
+   Unlike classic ABAC models, where a `mismatch` is simply ignored, Ability uses a **state‑machine model**:
+
+- `match` sets the state (`permit` → allow, `deny` → deny),
+- `mismatch` **resets the state to neutral**,
+- the final result is determined by the **last processed policy**, not just the one that matched.
+
+3. **Rules within a policy are also executed sequentially.**
 
-## Fundamentals
+4. **In a rule set with the `all` operator, execution stops at the first `mismatch`.**
+   In `any` – at the first `match`.
 
-Let’s briefly list the key points you need to know before starting to use the package:
+5. **Use [DSL](#dsl) to compose policies** – it's simpler and more convenient.
 
-1. The resolver (`AbilityResolver`) follows the **Default Deny** principle. This means that if no policy matches, the result is `deny` ([more details here](#troubleshooting)). To avoid unexpected `deny`, ensure there is at least one `permit` policy that can match. Only then add `deny` policies.
-2. Policies are applied sequentially. If multiple policies match, the result is determined by the last matching policy.
-3. Rules are executed sequentially.
-4. In a rule set (`RuleSet`) with the `all` comparison operator, further rule execution stops as soon as the first rule returns `mismatch`.
-5. Use [DSL](#dsl) to compose policies — it's simpler and more convenient.
-6. For storing policies on the server, use JSON. Policies can be exported to JSON and imported from JSON.
-7. Generally, rely on the principle: if permission is not explicitly granted → access is denied.
-8. Use the built-in cache only if your policies are incredibly complex and contain a large number of rules.
+6. **Use JSON to store policies on the server.**
+   Policies can be exported to JSON and imported back.
 
-### Interaction Model
+7. **Follow the principle: if permission is not explicitly granted → access is denied.**
+   This is a natural consequence of the `Default Deny` model and state‑machine behavior.
 
-First, you define "raw" policies (using DSL, JSON, or classes). Then, you transform the raw data into ready-to-use policies (an array of policies). This is done once and provides a single source of truth. After that, you can perform permission checks in any part of your code using the prepared policies and the resolver.
+### Interaction model
 
-Policies, rule sets, and rules can be created using:
+First, you describe "raw" policies (SDL, JSON, or using classes). Then, from the "raw" data, you form ready policies (an array of policies). This is done once and allows you to have a single source of truth. Then you can run permission checks in the necessary parts of your code using the already prepared policies and resolver.
+
+Policies, groups, and rules can be created using:
 
 - DSL (Domain-Specific Language)
 - Classes (classic approach)
 - JSON
 
-**Creating policies with DSL**
+**Creating policies using DSL**
 
 ```ts
 import { AbilityDSLParser } from '@via-profit/ability';
 
-// Describe policies using Ability-DSL
+// Describe policies in Ability-DSL language
 const dsl = `
-  # @name Order creation is only available to persons over 18 years old
+  # @name Creating an order is available only to persons over 18 years old
   permit permission.order.action.create if all:
     all of:
       user.age gte 18
 
-  # @name Price editing is only available to administrators
+  # @name Editing the price is available only to the administrator
   permit permission.order.data.price if all:
     all of:
       user.roles contains 'administrator'
 `;
 
 // Define resource types for TypeScript
-// Types can be generated automatically (more on this later) or defined manually
-// In this example, for simplicity, types are defined manually
+// Types can be generated automatically (more on that later), or described manually
+// In this example, for simplicity, types are described manually
 type Resources = {
   ['order.action.create']: {
     user: {
@@ -167,29 +191,29 @@ type Resources = {
 }
 
 // Use the parser to create policies
-// Pass the resource type as a generic parameter
+// Pass the resource type as a generic
 const policies = new AbilityDSLParser<Resources>(dsl).parse(); // AbilityPolicy[]
 
-// The parser returns an array of policies even
+// The parser will return an array of policies even
 // if only one policy is described in the DSL
 console.log(policies); // [AbilityPolicy, AbilityPolicy, ...]
 
-// Export the ready-to-use policies
+// export ready policies
 export default policies;
 ```
 
-For more details about DSL, see the [DSL](#dsl) section.
+For more details on DSL, see the section (DSL)[#dsl]
 
 **Creating policies using classes (classic approach)**
 
-This approach is quite verbose but gives you full control over the policies.
+This approach is quite verbose, but gives you full control over policies
 
 ```ts
 import { AbilityPolicy, AbilityRuleSet, AbilityRule, AbilityCompare, AbilityPolicyEffect } from '@via-profit/ability';
 
 // Define resource types for TypeScript
-// Types can be generated automatically (more on this later) or defined manually
-// In this example, for simplicity, types are defined manually
+// Types can be generated automatically (more on that later), or described manually
+// In this example, for simplicity, types are described manually
 type Resources = {
   ['order.action.create']: {
     user: {
@@ -207,7 +231,7 @@ const policies = [
   // first policy
   new AbilityPolicy<Resources>({
     id: '1',
-    name: 'Order creation is only available to persons over 18 years old',
+    name: 'Creating an order is available only to persons over 18 years old',
     compareMethod: AbilityCompare.and,
     effect: AbilityPolicyEffect.permit,
     permission: 'order.action.create',
@@ -221,7 +245,7 @@ const policies = [
   // second policy
   new AbilityPolicy<Resources>({
     id: '2',
-    name: 'Price editing is only available to administrators',
+    name: 'Editing the price is available only to the administrator',
     compareMethod: AbilityCompare.and,
     effect: AbilityPolicyEffect.permit,
     permission: 'order.data.price',
@@ -233,22 +257,22 @@ const policies = [
   ),
 ];
 
-// Export the ready-to-use policies
+// export ready policies
 export default policies;
 ```
 
-**Creating policies with JSON**
+**Creating policies using JSON**
 
 JSON allows you to store policies in a file or database, for example, in PostgreSQL, which supports working with JSON data.
 
-Policy, rule set, and rule classes have JSON export methods, so you can create policies in any way and export them to JSON whenever needed.
+Policy, group, and rule classes have methods to export to JSON, so you can form policies in any way and export them to JSON whenever you need it
 
 ```ts
 import { AbilityJSONParser } from '@via-profit/ability';
 
 // Define resource types for TypeScript
-// Types can be generated automatically (more on this later) or defined manually
-// In this example, for simplicity, types are defined manually
+// Types can be generated automatically (more on that later), or described manually
+// In this example, for simplicity, types are described manually
 type Resources = {
   ['order.action.create']: {
     user: {
@@ -263,11 +287,11 @@ type Resources = {
 }
 
 // Parse JSON using AbilityJSONParser
-// Pass the resource types as a generic parameter
+// Pass the resource types as a generic
 const policies = AbilityJSONParser.parse<Resources>([
   {
     id: '1',
-    name: 'Order creation is only available to persons over 18 years old',
+    name: 'Creating an order is available only to persons over 18 years old',
     effect: 'permit',
     permission: 'order.action.create',
     compareMethod: 'and',
@@ -286,7 +310,7 @@ const policies = AbilityJSONParser.parse<Resources>([
   },
   {
     id: '2',
-    name: 'Price editing is only available to administrators',
+    name: 'Editing the price is available only to the administrator',
     effect: 'permit',
     permission: 'order.data.price',
     compareMethod: 'and',
@@ -307,18 +331,19 @@ const policies = AbilityJSONParser.parse<Resources>([
 
 export default policies;
 ```
+
 ---
 
 ## DSL
 
 > DSL - Domain-Specific Language
 
-Ability DSL is a declarative language for describing access policies.  
+Ability DSL is a declarative language for describing access policies.
 It allows you to define rules in a human-readable form using simple constructs: *policies*, *groups*, *rules*, and *annotations*.
 
-### Policy Structure
+### Policy structure
 
-A policy consists of:
+A policy consists of the following construct:
 
 ```
 <effect> <permission> if <all|any>:
@@ -327,14 +352,14 @@ A policy consists of:
 
 Where:
 
-- **effect** — `permit` or `deny`
-- **permission** — a string of the form `permission.foo.bar`, where the `permission.` prefix is mandatory.
-- **if all:** — all groups must be true
-- **if any:** — at least one group must be true
+- **effect** – `permit` or `deny`
+- **permission** – a string like `permission.foo.bar`
+  (the `permission.` prefix is required in DSL but automatically removed by the parser)
+- **if all:** – all groups must be true
+- **if any:** – at least one group must be true
+- a policy can contain one or more rule groups
 
-A policy can contain one or more rule groups.
-
-Example:
+**Example**
 
 ```dsl
 permit permission.order.update if any:
@@ -347,36 +372,67 @@ permit permission.order.update if any:
     user.login is equals 'dev'
 ```
 
-> The `permission.` prefix is mandatory in DSL but is automatically removed by the parser. Internally, the permission is stored as `order.update`.
+This policy means:
+
+The `permission.order.update` permission will be granted if **at least one** of the two groups is satisfied:
+
+1. `user.roles` contains `'admin'` **and** `user.token` is not `null`
+2. `user.roles` contains `'developer'` **or** `user.login` equals `'dev'`
+
+If multiple policies match the key, they are **all executed**, top to bottom.
+
+Each policy:
+
+- **match**  
+  → sets a new state (`permit` → allow, `deny` → deny)
 
-The example policy above says: permission `order.update` will be allowed if one of two conditions is met:
-1. `user.roles` contains 'admin' **and** `user.token` is not null
-2. `user.roles` contains 'developer' **or** `user.login` equals 'dev'
+- **mismatch**  
+  → **resets the state** to `neutral`  
+  (i.e., cancels the result of the previous policy)
 
-### Permission Key
+The final decision is determined by the **last processed policy**, not just the one that matched.
 
-Permission keys are written in dot notation but support the use of wildcard patterns with the `*` character. This allows grouping of keys and overriding policies with similar keys.
+This means:
 
-If multiple policies match a key, **all of them are executed**. The final result is determined by the **last matching policy**:
+- a policy can **override** the previous one
+- a policy can **cancel** the previous one (via mismatch)
+- the order of policies in DSL is critically important
 
-**Example of using wildcards**
+### Permission key
 
-| Policy (permission) | Key                   | Matches |
-|---------------------|-----------------------|---------|
-| `order.*`           | `order.create`        | yes     |
-| `order.*`           | `order.update`        | yes     |
-| `order.*`           | `user.create`         | no      |
-| `*.create`          | `order.create`        | yes     |
-| `*.create`          | `user.create`         | yes     |
-| `*.create`          | `order.update`        | no      |
-| `user.profile.*`    | `user.profile.update` | yes     |
-| `user.profile.*`    | `user.settings.update`| no      |
+Permission keys are written in `dot notation` and support wildcard patterns using the `*` symbol.
+This allows grouping permissions and overriding behavior for entire families of operations.
+
+**How policy matching works**
+
+If multiple policies match the key, **all policies are executed in order**, top to bottom.
+The final decision is determined by the **last state** set during processing.
+
+This means:
+
+- a policy can **override** the result of the previous one
+- a policy can **cancel** the result of the previous one (via mismatch)
+- the order of policies in DSL is critically important
+
+### Example of using wildcards
+
+| Policy (permission) | key                    | Matches |
+|---------------------|------------------------|---------|
+| `order.*`           | `order.create`         | yes     |
+| `order.*`           | `order.update`         | yes     |
+| `order.*`           | `user.create`          | no      |
+| `*.create`          | `order.create`         | yes     |
+| `*.create`          | `user.create`          | yes     |
+| `*.create`          | `order.update`         | no      |
+| `user.profile.*`    | `user.profile.update`  | yes     |
+| `user.profile.*`    | `user.settings.update` | no      |
+
+### Example policy with wildcard
 
-**Example of a policy with wildcard**
 ```ts
 import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
 
-// DSL is not complete, shown for illustration only
+// DSL is incomplete and shown only for example
 const dsl = `
 permit permission.order.*
 deny permission.order.update
@@ -388,42 +444,47 @@ const resolver = new AbilityResolver(policies);
 resolver.enforce('order.update', resource); // will throw AbilityError
 ```
 
+---
+
 **Explanation**
 
-In DSL, the order of policies matters:
-the last matching policy wins.
+The order of policies in DSL determines the final decision.
 
-Therefore:
+Processing goes top to bottom:
 
-1. `permit` `permission.order.*` allows everything that starts with `order.`
-2. `deny` `permission.order.update` overrides this permission.
+1. `permit permission.order.*`
+- match → state = `allow`
 
-Execution result:
+2. `deny permission.order.update`
+- match → state = `deny`
+- the final state overwrites the previous one
+
+Result:
 
 ```
 order.update → deny
-order.create → permit
-order.delete → permit
-order.view   → permit
+order.create → allow
+order.delete → allow
+order.view   → allow
 ```
 
 ### Comments
 
-Lines starting with the `#` symbol are considered comments and do not affect the evaluation of rules and policies.
+Lines starting with the `#` symbol are considered comments and do not affect the result of rules and policies.
 
 ---
 
 ### Annotations
 
-Currently, only one annotation is supported: `name`, which will be used as the name for a policy, rule group, or rule.
+Currently, only one annotation is supported – ’name’, which will be used as the name for the policy, rule group, or rule.
 
-Annotations are specified via comments:
+Annotations are set via comments:
 
 ```
 # @name <name>
 ```
 
-Annotations apply to the **following entity**:
+Annotations apply to the **next entity**:
 
 - policy
 - group
@@ -442,9 +503,9 @@ permit permission.order.update if any:
 
 ---
 
-### Rule Groups
+### Rule groups
 
-A group defines how the rules within it are combined:
+A group defines how rules are combined within it:
 
 ```
 all of:
@@ -456,14 +517,14 @@ any of:
   <rule>
 ```
 
-- `all of:` — logical AND
-- `any of:` — logical OR
+- `all of:` – logical AND
+- `any of:` – logical OR
 
-`all of` means that the group is considered satisfied if all rules within the group match.
+`all of` – means the group is considered satisfied if all rules within the group matched.
 
-`any of` means that the group is considered satisfied if at least one rule within the group matches.
+`any of` – means the group is considered satisfied if at least one rule within the group matched.
 
-Each group within a policy will be evaluated independently of other groups. The final result is determined by comparing the results of all groups in the policy.
+Each group inside a policy will be evaluated independently of other groups. The final result will be determined by comparing the evaluation results of all groups in the policy.
 
 Groups can have annotations:
 
@@ -477,12 +538,12 @@ any of:
 
 ### Rules
 
-A rule is an atomic condition inside a policy. It defines under what data the policy is considered matched. Rules set the conditions that determine the effectiveness of a policy (`permit` or `deny`).
+A rule is an atomic condition inside a policy. It defines under what data the policy will be considered matching. Rules are used to set conditions that determine the policy's effect (`permit` or `deny`).
 
 A rule has the form:
 
 ```
-<subject> <operator> <value?> — the value is not required for some operators (e.g., `is null` does not require a value).
+<subject> <operator> <value?> — value is not specified for all operators (e.g., is null does not require a value).
 ```
 
 #### Subject
@@ -497,12 +558,12 @@ order.total
 
 #### Operators
 
-*Synonyms are alternative forms of writing that are also supported by the parser.*
+_Synonyms are alternative forms of notation that are also supported by the parser._
 
-**Basic Comparison Operators**
+**Basic comparison operators**
 
 | DSL Operator | Synonyms | Example | Description | Types |
-|--------------|----------|---------|-------------|-------|
+|--------------|----------|--------|----------|------|
 | **is equals** | `=`, `==`, `equals` | `age is equals 18` | Strict equality | number, string, boolean |
 | **is not equals** | `!=`, `<>`, `not equals` | `role is not equals 'admin'` | Strict inequality | number, string, boolean |
 | **greater than** | `>`, `gt` | `age greater than 18` | Greater than | number, date |
@@ -510,68 +571,64 @@ order.total
 | **less than** | `<`, `lt` | `age less than 18` | Less than | number, date |
 | **less than or equal** | `<=`, `lte` | `age less than or equal 18` | Less than or equal | number, date |
 
-**Null Operators**
+**Null operators**
 
 | DSL Operator | Synonyms | Example | Description | Types |
-|--------------|----------|---------|-------------|-------|
+|--------------|----------|--------|----------|------|
 | **is null** | `== null`, `= null` | `middleName is null` | Value is absent | any |
 | **is not null** | `!= null` | `middleName is not null` | Value is present | any |
 
-**Operators for Lists (Arrays)**
+**Operators for lists (arrays)**
 
 | DSL Operator | Synonyms                  | Example | Description | Types |
-|--------------|---------------------------|---------|-------------|-------|
+|--------------|---------------------------|--------|----------|------|
 | **in [...]** | -                         | `role in ['admin', 'manager']` | Value is in the list | number, string |
 | **not in [...]** | -                         | `role not in ['banned']` | Value is not in the list | number, string |
-| **contains** | `includes`, `has`         | `tags contains 'vip'` | Array contains the element | array |
-| **not contains** | `not includes`, `not has` | `tags not contains 'vip'` | Array does not contain the element | array |
+| **contains** | `includes`, `has`         | `tags contains 'vip'` | Array contains element | array |
+| **not contains** | `not includes`, `not has` | `tags not contains 'vip'` | Array does not contain element | array |
 
-**Boolean Operators**
+**Boolean operators**
 
 | DSL Operator | Synonyms | Example | Description | Types |
-|--------------|----------|---------|-------------|-------|
+|--------------|----------|--------|----------|------|
 | **is true** | `= true` | `isActive is true` | Value is true | boolean |
 | **is false** | `= false` | `isActive is false` | Value is false | boolean |
 
-**Length Operators**
+**Length operators**
 
 | DSL Operator | Synonyms | Example | Description | Types |
-|--------------|----------|---------|-------------|-------|
+|--------------|----------|--------|----------|------|
 | **length equals** | `len =` | `tags length equals 3` | Length equals | array, string |
 | **length greater than** | `len >` | `tags length greater than 2` | Length greater than | array, string |
 | **length less than** | `len <` | `tags length less than 5` | Length less than | array, string |
 
-Here is the English version, keeping the structure and tone consistent with your documentation style.
-
-**Special Operators**
+**Special operators**
 
 | DSL Operator | Synonyms | Example | Description | Types |
-|--------------|----------|---------|-------------|--------|
-| **always** | — | `always` | The condition is always true. Used for global allow rules or simplifying logic. | special operator |
-| **never** | — | `never` | The condition is always false. Used for global deny rules or disabling a rule. | special operator |
-
+|--------------|----------|--------|----------|------|
+| **always** | — | `always` | Condition always true. Used for global permission or simplifying logic. | special operator |
+| **never** | — | `never` | Condition always false. Used for global denial or disabling a rule. | special operator |
 
 **always**
-An operator that always returns `true`.  
+An operator that always returns `true`.
 Used for:
 
-- global allow (`permit permission.* if all: always`)
+- global permission (`permit permission.* if all: always`)
 - testing
 - disabling complex conditions
 - creating fallback rules
 
 **never**
-An operator that always returns `false`.  
+An operator that always returns `false`.
 Used for:
 
-- global deny (`deny permission.* if all: never`)
+- global denial (`deny permission.* if all: never`)
 - temporarily disabling a rule
-- explicit unconditional rejection
-
+- explicit negation without conditions
 
 #### Value
 
-Supported values:
+Supported:
 
 - strings `'text'`
 - numbers `42`
@@ -585,7 +642,7 @@ Examples:
 # user age greater than 18
 user.age greater than 18
 
-# array of roles contains the role 'admin'
+# array of roles contains role 'admin'
 user.roles contains 'admin'
 
 # order tag is either 'vip' or 'priority'
@@ -600,9 +657,9 @@ user.login length greater than 12
 
 ---
 
-### Implicit Group
+### Implicit group
 
-If rules are written without `all of:` or `any of:`, they are combined using the policy operator:
+If rules are written without `all of:` or `any of:`, they are combined by the policy operator:
 
 ```dsl
 permit permission.order.update if all:
@@ -623,33 +680,33 @@ The implicit group always matches the policy operator (`if all` or `if any`).
 
 ---
 
-### Complete Example
+### Full example
 
 ```dsl
 # @name order update allowed
 permit permission.order.update if any:
 
-  # @name if admin
+  # @name if this is admin
   all of:
     user.roles contains 'admin'
     user.token is not null
 
-  # @name if developer
+  # @name if this is developer
   any of:
     user.roles contains 'developer'
     user.login is equals 'dev'
 ```
 
-## Combining Policies
+## Combining policies
 
-In a real project, you should use multiple policies at once.
+In a real project, you should use several policies at once.
 
 TODO: using multiple policies
 
 ## Policy Environment
 
-**Environment** is an object containing context data that does not belong to either the user or the resource.  
-The content of the object is defined by the developer and can be any object consisting of primitives.
+**Environment** is an object containing environment data that does not belong to either the user or the resource.
+The content of the object is defined by the developer and can be any object composed of primitives.
 
 - request time,
 - IP address,
@@ -658,8 +715,7 @@ The content of the object is defined by the developer and can be any object cons
 - session context,
 - any other external conditions.
 
-
-Environment is passed to `resolve()` and `enforce()` as the third argument:
+The environment is passed to `resolve()` and `enforce()` as the third argument:
 
 ```ts
 const environment = {
@@ -674,7 +730,7 @@ resolver.enforce('order.update', resource, environment);
 
 ### Using environment in rules
 
-In a policy, you can refer to environment via the `env.*` path.
+In a policy, you can refer to the environment via the path `env.*`.
 
 Example policy that denies order updates at night (10 PM – 6 AM):
 
@@ -687,7 +743,7 @@ deny permission.order.update if all:
 
 **Retrieving values from environment**
 
-If a path is specified in a rule:
+If the rule specifies a path:
 
 - `env.*` → value is taken from environment
 - `user.*`, `order.*`, `profile.*` → from resource
@@ -703,7 +759,7 @@ condition: "equal"
 
 ### Environment in TypeScript
 
-The Environment type is set at the `AbilityResolver` level:
+The Environment type is specified at the `AbilityResolver` level:
 
 ```ts
 const resolver = new AbilityResolver<Resources, Environment>(policies);
@@ -711,17 +767,17 @@ const resolver = new AbilityResolver<Resources, Environment>(policies);
 
 This allows:
 
-- getting autocompletion in IDE,
+- getting autocompletion in the IDE,
 - checking the correctness of `env.*` paths,
-- avoiding errors when passing environment.
+- avoiding errors when passing the environment.
 
-> If a rule uses `env.*` but environment is not passed, then the value of `env.*` will be `undefined`, and the comparison will be performed as if the environment were absent.
+> If a rule uses `env.*` but the environment is not passed, the `env.*` value will be `undefined`, and the comparison will be performed as if the environment were not present at all.
 
-## TypeScript Type Generator
+## TypeScript type generator
 
-`AbilityTypeGenerator.generateTypeDefs(policies)` generates TypeScript types based on policies, allowing you to avoid inconsistencies between types and the data in the policies.
+`AbilityTypeGenerator.generateTypeDefs(policies)` generates types for TypeScript based on policies, allowing you not to worry about discrepancies between types and data in policies.
 
-**Example usage**
+**Usage example**
 
 Policies can be stored in DSL or JSON. This example uses a DSL file.
 
@@ -746,7 +802,7 @@ const { AbilityTypeGenerator, AbilityDSLParser } = require('@via-profit/ability'
 const dslPath = path.resolve(__dirname, '../src/policies/policies.dsl');
 const typeDefsPath = path.join(path.dirname(dslPath), 'policies.types.ts');
 
-// Read DSL as a string
+// Read DSL as string
 const dsl = fs.readFileSync(dslPath, {encoding: 'utf-8'});
 
 // Create policies
@@ -770,7 +826,6 @@ const policies = new AbilityDSLParser<Resources>(dsl).parse();
 export const policyResolver = new AbilityResolver(new AbilityDSLParser<Resources>(dsl).parse());
 
 export default policyResolver;
-
 ```
 
 **Generated file (example)**
@@ -803,17 +858,17 @@ resolver.enforce('order.update', {
 });
 ```
 
-## Policy Debugging
+## Debugging policies
 
 ### Explanations
 
-To simplify policy debugging, a special `AbilityResult` class is used, which is already included in the final evaluation result. `AbilityResult` encapsulates the outcome of applying all matching policies to a permission key and resource.
+To simplify policy debugging, a special class `AbilityResult` is used, which is already included in the final calculation result. `AbilityResult` encapsulates the result of applying all matching policies to the permission key and resource.
 
 `AbilityResult` contains:
 
-- a list of evaluated policies,
+- list of evaluated policies,
 - methods to determine the final effect,
-- methods to get explanations in textual representation.
+- methods to get explanations in text representation.
 
 Example:
 
@@ -835,8 +890,8 @@ const explanations = result.explain(); // AbilityExplain
 
 - which policy matched,
 - which rule groups matched,
-- which rules did not pass,
-- which effect was applied.
+- which rules failed,
+- what effect was applied.
 
 Usage example:
 
@@ -858,17 +913,17 @@ Example output:
     ✓ rule «No role administrator» is match
 ```
 
-### Output Format
+### Output format
 
-Currently, only one output format is supported — textual.
+Currently, only one output format is supported – text.
 
-The output follows the principle: `<policy | ruleSet | rule> <name> <is match | is mismatch>`
+The output is structured as: <policy | ruleSet | rule > <name> <is match | is mismatch>
 
 ## Troubleshooting
 
-### Decision‑Making Model (Default Deny)
+### Decision model (Default Deny)
 
-> Why does a `deny` policy not turn into `permit` if its conditions are not met?
+> Why doesn't a `deny` policy turn into `permit` if its conditions are not met?
 
 Consider a policy that **denies** access to a user aged 16:
 
@@ -889,10 +944,10 @@ console.log(result.isDenied());  // true  ✔
 console.log(result.isAllowed()); // false ✔
 ```
 
-In this case, everything is obvious:  
-the condition is met → the policy matches → effect `deny` → access denied.
+In this case, everything is obvious:
+condition satisfied → policy matches → effect `deny` → access denied.
 
-**What happens if the conditions are *not met*?**
+**What happens if the conditions are `not satisfied`?**
 
 ```ts
 const result = resolver.resolve('test', {
@@ -903,66 +958,66 @@ console.log(result.isDenied());  // true  ✔
 console.log(result.isAllowed()); // false ✔
 ```
 
-At first glance, it might seem that if the condition is not met, the policy should “allow” access.  
-But that is **not the case**.
+At first glance, it might seem that if the condition is not met, the policy should "allow" access.
+But that's **not the case**.
 
-**Decision‑Making Model: `Default Deny`**
+**Decision model: `Default Deny`**
 
 `AbilityResolver` uses the classic security model:
 
-> **If there is no matching permit‑policy → access is denied.**
+> **If there is no matching permit policy → access denied.**
 
 **What happens in this example:**
 
-1. The `deny` policy exists, but its condition is **not met**  
-   → the policy gets status `mismatch`.
+1. The `deny` policy exists, but its condition is **not satisfied**
+   → the policy gets `mismatch` status.
 
-2. The `deny` policy **is not applied** because the conditions did not match.
+2. The `deny` policy **does not apply** because the conditions did not match.
 
 3. There is no `permit` policy.
 
-4. Since there is no permit policy → the final decision:  
+4. Since there is no granting policy → final decision:
    **deny (by default)**.
 
 **Summary**
 
 - `deny` with matching conditions → **deny**
-- `deny` with non‑matching conditions → **deny (default deny)**
+- `deny` with non-matching conditions → **deny (default deny)**
 - `permit` with matching conditions → **allow**
-- `permit` with non‑matching conditions → **deny (default deny)**
+- `permit` with non-matching conditions → **deny (default deny)**
 
 **Conclusion**
 
-**Access is allowed only if there is an explicit permit.**
+**Access is only granted when there is an explicit permit.**
 
-## Design Recommendations
+## Design recommendations
 
-### Naming Access Keys
+### Naming access keys
 
 - Use hierarchical keys: `permission.order.create`, `permission.order.update.status`, `permission.user.profile.update`.
 - Group by domains: `permission.user.*`, `permission.order.*`, `permission.product.*`.
 - Do not mix different domains in one key.
 
-### Data Structure
+### Data structure
 
 - Explicitly describe `Resources` in TypeScript.
-- Do not pass “extra” fields — this complicates understanding.
-- Strive to keep the data structure for a given `permission` stable.
+- Do not pass "extra" fields – this complicates understanding.
+- Try to keep the data structure for a single `permission` stable.
 
-### Policy Design
+### Designing policies
 
-- General rules — via wildcard (`permission.order.*`).
-- Specific restrictions — via exact actions (`permission.order.update`).
+- Common rules – via wildcard (`permission.order.*`).
+- Specific restrictions – via exact actions (`permission.order.update`).
 - Use `effect: deny` for prohibitions.
 - Use `effect: permit` for permissions.
 
-### Common Mistakes
+### Typical mistakes
 
-- Expecting that absence of matching policies means allow.
+- Expecting that the absence of matching policies means deny.
 - Mixing business logic and access policies.
-- Too large policies with dozens of rules — better to break them down.
+- Too large policies with dozens of rules – it's better to split them.
 
-### Example of Use on the Frontend (React)
+### Example of use on the frontend (React)
 
 **Hook for checking policies**
 
@@ -1006,7 +1061,7 @@ export function useAbility<Permission extends keyof Resources>(
 }
 ```
 
-**Usage in a component**
+**Usage in component**
 
 ```tsx
 function OrderUpdateButton({ order, user }) {
@@ -1016,7 +1071,7 @@ function OrderUpdateButton({ order, user }) {
   });
 
   if (allowed === null) {
-    return null; // or loading spinner
+    return null; // or loading badge
   }
 
   if (!allowed) {
@@ -1029,177 +1084,125 @@ function OrderUpdateButton({ order, user }) {
 
 ## Examples
 
-### Example of a Complex Multi‑Level Policy
+### Example of a complex multi-stage policy
 
-Below is a multi‑level set of policies, using a cinema example (fictional).
+Below is an example of a set of policies for a cinema.
+It demonstrates:
 
-**The example demonstrates:**
 - working with roles (admin, seller, manager, VIP, banned),
-- time constraints (`env.time.hour`),
+- time restrictions (`env.time.hour`),
 - wildcard permissions (`permission.*`),
-- ticket quantity limits,
+- ticket quantity restrictions,
 - prohibition on selling already sold tickets,
-- combination of `permit`/`deny` policies,
-- policy priority and Default Deny model.
-
-**Brief description of rules**
-- **Administrator**  
-  Has wildcard permissions (`permission.*`) and can perform any action.  
-  Can edit ticket prices.
-
-- **Seller**  
-  Can sell tickets only during working hours (09:00–23:00).  
-  Cannot sell tickets if:
-    - the cinema is closed,
-    - the ticket is already sold.
-
-- **Manager**  
-  Has the same rights as a seller.
+- combination of `permit`/`deny`,
+- **sequential processing of policies**,
+- **state‑machine model**, where each policy can **set or reset the state**.
 
-- **Buyers**
-    - A user older than 21 can buy tickets.
-    - A VIP user can buy tickets at any time.
-    - A banned user (`status = banned`) cannot buy tickets.
-    - Any user cannot buy more than 6 tickets.
-
-**Policy Diagram**
-
-```mermaid
-flowchart LR
-
-%% ==== ROLES ====
-
-   subgraph Roles[Roles]
-      A[Administrator]
-      B[Seller]
-      C[Manager]
-   end
-
-   subgraph Buyers[Buyers]
-      U1[User > 21]
-      U2[VIP user]
-      U3[Banned user]
-   end
-
-%% ==== ADMIN ====
-
-   A --> A1[Wildcard: permission.*]
-   A --> A2[Edit ticket price]
-
-   A1 --> FINAL[Final decision]
-   A2 --> FINAL
+---
 
-%% ==== SELLER ====
+**Unlike classic ABAC systems, where `mismatch` is ignored, Ability uses a `state‑machine` model:**
 
-   B --> B1[Sell tickets]
+- **match** → policy sets a state (`allow` or `deny`)
+- **mismatch** → policy **resets the state to neutral**
+- the final result is determined by the **last processed policy**
 
-   B1 -->|09:00–23:00| B2[Allowed]
-   B1 -->|Outside hours| D2[Denied]
-   B1 -->|ticket.status = sold| D3[Denied]
+This means:
 
-   B2 --> FINAL
-   D2 --> FINAL
-   D3 --> FINAL
+- a policy can **override** the previous one
+- a policy can **cancel** the previous one (via mismatch)
+- the order of policies in DSL is critically important
+- the final decision does not always match the “intuitive” reading of rules from top to bottom
 
-%% ==== MANAGER ====
+### Brief description of the rules
 
-   C --> C1[Sell tickets as seller]
-   C1 --> FINAL
+**Administrator**
 
-%% ==== BUYERS ====
+- Has wildcard rights (`permission.*`)
+- Can edit ticket prices
 
-   U1 --> U1A[Buy tickets]
-   U1A -->|ticketsCount < 6| U1OK[Allowed]
-   U1A -->|ticketsCount ≥ 6| U1DENY[Denied]
+**Seller**
 
-   U2 --> U2A[Buy tickets anytime]
-   U2A -->|ticketsCount < 6| U2OK[Allowed]
-   U2A -->|ticketsCount ≥ 6| U2DENY[Denied]
+- Can sell tickets only during working hours (09:00–23:00)
+- Cannot sell tickets if:
+  - the cinema is closed,
+  - the ticket is already sold
 
-   U3 --> U3A[Denied to buy tickets]
+**Manager**
 
-   U1OK --> FINAL
-   U1DENY --> FINAL
-   U2OK --> FINAL
-   U2DENY --> FINAL
-   U3A --> FINAL
+- Has the same rights as the seller
 
-%% ==== DENY RULES ====
+**Buyers**
 
-   D1[Denied to buy tickets if user.status = banned] --> FINAL
-```
+- A user over 21 years old can buy tickets
+- A VIP user can buy tickets at any time
+- A banned user (`status = banned`) cannot buy tickets
+- Any user cannot buy more than 6 tickets
 
-**DSL Policies**
+### DSL policies
 
 ```dsl
-############################################################
-# @name Admin can edit ticket price
 permit permission.ticket.price.edit if all:
   user.role is equals 'admin'
 
-
-############################################################
-# @name Seller can sell tickets during working hours
 permit permission.ticket.sell if all:
   user.role is equals 'seller'
   all of:
     env.time.hour greater than or equal 9
     env.time.hour less than or equal 23
 
-
-############################################################
-# @name Users older than 21 can buy tickets
 permit permission.ticket.buy if all:
   user.age greater than 21
 
-
-############################################################
-# @name VIP users can buy tickets anytime
 permit permission.ticket.buy if all:
   user.isVIP is true
 
-
-############################################################
-# @name Deny buying tickets if user is banned
 deny permission.ticket.buy if all:
   user.status is equals 'banned'
 
-
-############################################################
-# @name Deny selling tickets if cinema is closed
 deny permission.ticket.sell if all:
   any of:
     env.time.hour less than 9
     env.time.hour greater than 23
 
-
-############################################################
-# @name Manager can do everything seller can
 permit permission.ticket.sell if all:
   user.role is equals 'manager'
 
-
-############################################################
-# @name Admin wildcard permissions
 permit permission.* if all:
   user.role is equals 'admin'
 
-
-############################################################
-# @name Limit tickets per user (max 6)
 deny permission.ticket.buy if all:
   user.ticketsCount greater than or equal 6
 
-
-############################################################
-# @name Cannot sell already sold tickets
 deny permission.ticket.sell if all:
   ticket.status is equals 'sold'
 ```
 
-Below is how to use the policies above in Node.js + TypeScript.
+**Example: seller sells a ticket at 3:00 PM**
+
+1. permit seller match → `allow`
+2. deny closed mismatch → `neutral`
+3. deny sold mismatch → `neutral`
+
+Result: `neutral → deny`
+
+**Example: VIP buys a ticket at night**
+
+1. permit age>21 mismatch → `neutral`
+2. permit VIP match → `allow`
+3. deny banned mismatch → `neutral`
+4. deny limit mismatch → `neutral`
+
+Result: `neutral → deny`
+
+**Example: administrator sells a ticket at night**
+
+1. permit admin wildcard match → `allow`
+2. deny closed match → `deny`
+3. deny sold mismatch → `neutral`
+
+Result: `neutral → deny`
 
-**Preparing Policies**
+### Preparing policies
 
 ```ts
 import { AbilityDSLParser } from '@via-profit/ability';
@@ -1208,7 +1211,7 @@ import cinemaDSL from './policies/cinema.dsl';
 export const policies = new AbilityDSLParser(cinemaDSL).parse();
 ```
 
-**Creating the Resolver**
+### Creating a resolver
 
 ```ts
 import { AbilityResolver } from '@via-profit/ability';
@@ -1217,11 +1220,7 @@ import { policies } from './policies';
 const resolver = new AbilityResolver(policies);
 ```
 
-**Checking Permissions (enforce)**
-
-Example: buying a ticket.
-
-The `enforce` method throws an `AbilityError` if access is denied.
+### enforce (throws an error on deny)
 
 ```ts
 resolver.enforce('ticket.buy', {
@@ -1229,12 +1228,8 @@ resolver.enforce('ticket.buy', {
   env: { time: { hour: 18 } },
 });
 ```
-If allowed — the code continues execution.  
-If denied — an `AbilityError` exception is thrown.
-
-**Checking Permissions Without Exceptions (resolve)**
 
-`resolve` returns a result object:
+### resolve (without exceptions)
 
 ```ts
 const result = resolver.resolve('ticket.buy', {
@@ -1249,19 +1244,9 @@ if (result.isAllowed()) {
 }
 ```
 
-**Seller can only sell during working hours**
+**Preparing data for the resolver**
 
-```ts
-resolver.enforce('ticket.sell', {
-  user: { role: 'seller' },
-  env: { time: { hour: 15 } },
-  ticket: { status: 'available' },
-});
-```
-
-**Preparing Data for the Resolver**
-
-In the examples above, constant objects are passed to the resolver:
+In the examples above, simple constant objects are passed to the resolver:
 
 ```ts
 resolver.enforce('ticket.buy', {
@@ -1270,7 +1255,7 @@ resolver.enforce('ticket.buy', {
 });
 ```
 
-This is done for clarity. In a real application, the data for the resolver should be built dynamically — from the sources available to your server.
+This is done for clarity. In a real application, the data for the resolver should be formed dynamically – from the sources available to your server.
 
 **User** (`user`) is usually taken from:
 
@@ -1285,7 +1270,7 @@ Example:
 const user = await db.users.findById(session.userId);
 ```
 
-**Environment** (`env`)
+**Environment (`env`)**
 
 These are any external parameters that can affect access:
 
@@ -1308,7 +1293,7 @@ const env = {
 
 **Resource** (e.g., `ticket`)
 
-If the action is associated with a specific object, it also needs to be loaded:
+If the action is related to a specific object – it also needs to be loaded:
 
 ```ts
 const ticket = await db.tickets.findById(req.params.ticketId);
@@ -1316,17 +1301,17 @@ const ticket = await db.tickets.findById(req.params.ticketId);
 
 **Context**
 
-Context is the object that you pass to `resolve` or `enforce`.  
-It contains **all the data** that policies might need:
+The context is the object you pass to `resolve` or `enforce`.
+It contains **all the data** that policies may need:
 
-- `user` — data about the current user
-- `env` — environment data (time, IP, geography, system settings)
-- `resource` or `ticket` — data about the entity on which the action is performed
-- any other objects that you use in DSL
+- `user` – data about the current user
+- `env` – environment data (time, IP, geography, system settings)
+- `resource` or `ticket` – data about the entity on which the action is performed
+- any other objects you use in the DSL
 
-**It is important to understand:**
+**Important to understand:**
 
-> Context is formed for a specific action and specific policies. It does not need to be stored in advance — you gather it dynamically before calling the resolver.
+> The context is formed for a specific action and specific policies. You don't need to store it in advance – you collect it dynamically before calling the resolver.
 
 ## Performance
 
@@ -1361,3 +1346,4 @@ Throughput (ops/s)
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](/LICENSE) file for details.
+```