@briza/illogical 2.2.0 → 2.2.2

package/lib/illogical.cjs

@@ -1810,6 +1810,12 @@ const OP_NOR = 55; // next: N — marker for NOR with N operands
 const OP_IN_SCAN_REFS_CONST = 56;
 // next: N, ref0..refN-1, constIdx — resolve each ref inline, check ∉ consts[constIdx], no stack alloc
 const OP_NOT_IN_SCAN_REFS_CONST = 57;
+// Marks the entry of a short-circuit AND/OR/NOR scope.
+// Emitted by the compiler at the start of every emitShortCircuit block.
+// The evaluate interpreter treats it as a no-op.
+// The simplify interpreter uses it to push a spill-buffer scope marker so that
+// nested AND/OR/NOR blocks cannot steal residuals accumulated by an outer scope.
+const OP_ENTER_SCOPE = 58;
 
 /**
  * Reference path descriptors for the bytecode compiler and interpreter.
@@ -2074,6 +2080,36 @@ function resolveCompactRef(ref, ctx) {
   }
   return resolveTokens(ref.tokens ?? [], ref.t, ctx);
 }
+function getKeyFromCompactRef(ref) {
+  if (typeof ref === 'string') {
+    return ref;
+  }
+  if (Array.isArray(ref)) {
+    return ref.map(ref => ref.includes('.') ? `\`${ref}\`` : ref).join('.');
+  }
+  let tokens = ref.tokens;
+  if (ref.d) {
+    let current = ref.k;
+    let match = dynamicKeyRegex.exec(current);
+    while (match) {
+      current = current.replace(dynamicKeyRegex, '').replace('[]', '');
+      match = dynamicKeyRegex.exec(current);
+    }
+    tokens = parseStaticKey(current);
+  }
+  let key = '';
+  for (const token of tokens ?? []) {
+    if (isNumber(token.value)) {
+      return key;
+    }
+    if (token.value.includes('.')) {
+      key += `${key ? '.' : ''}\`${token.value}\``;
+    } else {
+      key += `${key ? '.' : ''}${token.value}`;
+    }
+  }
+  return key;
+}
 
 /**
  * Bytecode compiler.
@@ -2389,6 +2425,7 @@ function emitShortCircuit(arr, jumpOp, markerOp, state) {
   } = state;
   const jumpSlots = [];
   const last = arr.length - 1;
+  bytecode.push(OP_ENTER_SCOPE);
   for (let i = 1; i < last; i++) {
     emitExpression(arr[i], state);
     bytecode.push(jumpOp);
@@ -3363,6 +3400,8 @@ function interpret(compiled, ctx) {
       case OP_POP:
         stackTop$1--;
         break;
+      case OP_ENTER_SCOPE:
+        break;
       case OP_AND:
       case OP_OR:
       case OP_NOR:
@@ -3649,10 +3688,12 @@ let resolvedRefUsedCount = 0;
 // can include it in the reconstructed expression.
 const spillBuf = new Array(MAX_STACK);
 let spillTop = -1;
-// Track the last jump opcode type to detect transitions between short-circuit
-// sequences. Different jump opcodes (41=JUMP_IF_FALSE vs 42=JUMP_IF_TRUE) indicate
-// different short-circuit sequences (AND vs OR/NOR).
-let lastJumpOp = 0;
+// Scope stack for the spill buffer: each OP_ENTER_SCOPE pushes the current
+// spillTop so that OP_AND/OR/NOR can drain only the entries added within their
+// own scope (base+1..spillTop) and restore the outer scope (spillTop = base).
+// This prevents nested AND/OR from stealing residuals accumulated by outer scopes.
+const scopeStack = new Array(MAX_STACK);
+let scopeStackTop = -1;
 function relationalCompare(left, right, op) {
   if (isNumber(left) && isNumber(right)) {
     if (op === OP_GT) {
@@ -3709,7 +3750,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
   } = compiled;
   stackTop = -1;
   spillTop = -1;
-  lastJumpOp = 0;
+  scopeStackTop = -1;
   let overlapRefsResiduals = overlapRefsResidualsCache.get(compiled);
   if (overlapRefsResiduals === undefined) {
     overlapRefsResiduals = new Map(compiled.overlapRefsResiduals);
@@ -3757,7 +3798,6 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
       case OP_PUSH_REF_DYNAMIC:
         {
           const idx = numAt(bytecode[i++]);
-          const rawKey = refRawKeys[idx];
           let val;
           if (resolvedRefDirty[idx]) {
             val = resolvedRefCache[idx];
@@ -3776,12 +3816,12 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           // Ref is absent from context.
           // Check if it should be treated as a concrete undefined (evaluated as undefined)
           // or as a residual expression (preserved for later simplification).
-          if (strictSet?.has(rawKey)) {
+          if (strictSet?.has(getKeyFromCompactRef(refs[idx]))) {
             // strictKeys: force-evaluate as undefined (not a residual)
             stack[++stackTop] = undefined;
             break;
           }
-          if (optionalSet && !optionalSet.has(rawKey)) {
+          if (optionalSet && !optionalSet.has(getKeyFromCompactRef(refs[idx]))) {
             // Key not in optionalKeys: treat as definitely-present but absent → undefined
             stack[++stackTop] = undefined;
             break;
@@ -4470,13 +4510,6 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           if (!needsReconstruct(top) && slotVal(top) === false) {
             i += offset;
           }
-          // Clear spill buffer when transitioning between short-circuit sequences.
-          // Different jump opcodes (41=JUMP_IF_FALSE for AND vs 42=JUMP_IF_TRUE for OR/NOR)
-          // indicate different short-circuit sequences.
-          if (lastJumpOp !== 41) {
-            spillTop = -1;
-          }
-          lastJumpOp = 41;
           break;
         }
       case OP_JUMP_IF_TRUE:
@@ -4486,13 +4519,11 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           if (!needsReconstruct(top) && slotVal(top) === true) {
             i += offset;
           }
-          // Clear spill buffer when transitioning between short-circuit sequences.
-          if (lastJumpOp !== 42) {
-            spillTop = -1;
-          }
-          lastJumpOp = 42;
           break;
         }
+      case OP_ENTER_SCOPE:
+        scopeStack[++scopeStackTop] = spillTop;
+        break;
       case OP_POP:
         {
           const popped = stack[stackTop--];
@@ -4507,15 +4538,19 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
       // AND/OR/NOR markers — collect the current stack top plus any residuals
       // that were spilled by OP_POP during the short-circuit sequence, then
       // apply the simplification logic.
+      //
+      // Each of these opcodes pops the scope base that was pushed by the
+      // matching OP_ENTER_SCOPE at the start of the short-circuit block. Only
+      // spill entries above that base (indices base+1..spillTop) belong to this
+      // scope; entries at 0..base belong to outer scopes and are preserved by
+      // restoring spillTop = base after draining.
       case OP_AND:
         {
           i++; // consume the operand count byte (unused — we use the spill buffer)
           const top = stack[stackTop--];
-          // Fast path: nothing was spilled — all non-top operands were concrete.
-          // The top is either a short-circuit false, the last true, or a lone residual.
-          // Push top directly — slotVal unwrapping happens at the final return point.
-          if (spillTop < 0) {
-            spillTop = -1;
+          const base = scopeStack[scopeStackTop--];
+          // Fast path: no entries were spilled in this scope.
+          if (spillTop === base) {
             if (!needsReconstruct(top)) {
               stack[++stackTop] = top;
             } else {
@@ -4524,10 +4559,8 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
             break;
           }
           const residuals = [];
-          // Drain spill buffer (residuals from earlier operands that were POP'd)
-          // Check if any spilled operand was false (dominates AND)
           let andDominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === false) {
               andDominated = true;
@@ -4537,8 +4570,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1; // clear spill buffer
-          // Include the stack top (last operand result)
+          spillTop = base; // restore outer scope
           if (!andDominated) {
             if (!needsReconstruct(top) && slotVal(top) === false) {
               andDominated = true;
@@ -4561,10 +4593,9 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
         {
           i++; // consume the operand count byte
           const top = stack[stackTop--];
-          // Fast path: nothing was spilled — all non-top operands were concrete.
-          // Push top directly — slotVal unwrapping happens at the final return point.
-          if (spillTop < 0) {
-            spillTop = -1;
+          const base = scopeStack[scopeStackTop--];
+          // Fast path: no entries were spilled in this scope.
+          if (spillTop === base) {
             if (!needsReconstruct(top)) {
               stack[++stackTop] = top;
             } else {
@@ -4574,7 +4605,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           }
           const residuals = [];
           let orDominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === true) {
               orDominated = true;
@@ -4584,7 +4615,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1;
+          spillTop = base; // restore outer scope
           if (!orDominated) {
             if (!needsReconstruct(top) && slotVal(top) === true) {
               orDominated = true;
@@ -4612,9 +4643,10 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           // OP_NOT will pass through unchanged.
           i++; // consume the operand count byte
           const top = stack[stackTop--];
+          const base = scopeStack[scopeStackTop--];
           const residuals = [];
           let dominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === true) {
               dominated = true;
@@ -4624,7 +4656,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1;
+          spillTop = base; // restore outer scope
           if (!dominated) {
             if (!needsReconstruct(top) && slotVal(top) === true) {
               dominated = true;

package/lib/illogical.esm.js

@@ -1806,6 +1806,12 @@ const OP_NOR = 55; // next: N — marker for NOR with N operands
 const OP_IN_SCAN_REFS_CONST = 56;
 // next: N, ref0..refN-1, constIdx — resolve each ref inline, check ∉ consts[constIdx], no stack alloc
 const OP_NOT_IN_SCAN_REFS_CONST = 57;
+// Marks the entry of a short-circuit AND/OR/NOR scope.
+// Emitted by the compiler at the start of every emitShortCircuit block.
+// The evaluate interpreter treats it as a no-op.
+// The simplify interpreter uses it to push a spill-buffer scope marker so that
+// nested AND/OR/NOR blocks cannot steal residuals accumulated by an outer scope.
+const OP_ENTER_SCOPE = 58;
 
 /**
  * Reference path descriptors for the bytecode compiler and interpreter.
@@ -2070,6 +2076,36 @@ function resolveCompactRef(ref, ctx) {
   }
   return resolveTokens(ref.tokens ?? [], ref.t, ctx);
 }
+function getKeyFromCompactRef(ref) {
+  if (typeof ref === 'string') {
+    return ref;
+  }
+  if (Array.isArray(ref)) {
+    return ref.map(ref => ref.includes('.') ? `\`${ref}\`` : ref).join('.');
+  }
+  let tokens = ref.tokens;
+  if (ref.d) {
+    let current = ref.k;
+    let match = dynamicKeyRegex.exec(current);
+    while (match) {
+      current = current.replace(dynamicKeyRegex, '').replace('[]', '');
+      match = dynamicKeyRegex.exec(current);
+    }
+    tokens = parseStaticKey(current);
+  }
+  let key = '';
+  for (const token of tokens ?? []) {
+    if (isNumber(token.value)) {
+      return key;
+    }
+    if (token.value.includes('.')) {
+      key += `${key ? '.' : ''}\`${token.value}\``;
+    } else {
+      key += `${key ? '.' : ''}${token.value}`;
+    }
+  }
+  return key;
+}
 
 /**
  * Bytecode compiler.
@@ -2385,6 +2421,7 @@ function emitShortCircuit(arr, jumpOp, markerOp, state) {
   } = state;
   const jumpSlots = [];
   const last = arr.length - 1;
+  bytecode.push(OP_ENTER_SCOPE);
   for (let i = 1; i < last; i++) {
     emitExpression(arr[i], state);
     bytecode.push(jumpOp);
@@ -3359,6 +3396,8 @@ function interpret(compiled, ctx) {
       case OP_POP:
         stackTop$1--;
         break;
+      case OP_ENTER_SCOPE:
+        break;
       case OP_AND:
       case OP_OR:
       case OP_NOR:
@@ -3645,10 +3684,12 @@ let resolvedRefUsedCount = 0;
 // can include it in the reconstructed expression.
 const spillBuf = new Array(MAX_STACK);
 let spillTop = -1;
-// Track the last jump opcode type to detect transitions between short-circuit
-// sequences. Different jump opcodes (41=JUMP_IF_FALSE vs 42=JUMP_IF_TRUE) indicate
-// different short-circuit sequences (AND vs OR/NOR).
-let lastJumpOp = 0;
+// Scope stack for the spill buffer: each OP_ENTER_SCOPE pushes the current
+// spillTop so that OP_AND/OR/NOR can drain only the entries added within their
+// own scope (base+1..spillTop) and restore the outer scope (spillTop = base).
+// This prevents nested AND/OR from stealing residuals accumulated by outer scopes.
+const scopeStack = new Array(MAX_STACK);
+let scopeStackTop = -1;
 function relationalCompare(left, right, op) {
   if (isNumber(left) && isNumber(right)) {
     if (op === OP_GT) {
@@ -3705,7 +3746,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
   } = compiled;
   stackTop = -1;
   spillTop = -1;
-  lastJumpOp = 0;
+  scopeStackTop = -1;
   let overlapRefsResiduals = overlapRefsResidualsCache.get(compiled);
   if (overlapRefsResiduals === undefined) {
     overlapRefsResiduals = new Map(compiled.overlapRefsResiduals);
@@ -3753,7 +3794,6 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
       case OP_PUSH_REF_DYNAMIC:
         {
           const idx = numAt(bytecode[i++]);
-          const rawKey = refRawKeys[idx];
           let val;
           if (resolvedRefDirty[idx]) {
             val = resolvedRefCache[idx];
@@ -3772,12 +3812,12 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           // Ref is absent from context.
           // Check if it should be treated as a concrete undefined (evaluated as undefined)
           // or as a residual expression (preserved for later simplification).
-          if (strictSet?.has(rawKey)) {
+          if (strictSet?.has(getKeyFromCompactRef(refs[idx]))) {
             // strictKeys: force-evaluate as undefined (not a residual)
             stack[++stackTop] = undefined;
             break;
           }
-          if (optionalSet && !optionalSet.has(rawKey)) {
+          if (optionalSet && !optionalSet.has(getKeyFromCompactRef(refs[idx]))) {
             // Key not in optionalKeys: treat as definitely-present but absent → undefined
             stack[++stackTop] = undefined;
             break;
@@ -4466,13 +4506,6 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           if (!needsReconstruct(top) && slotVal(top) === false) {
             i += offset;
           }
-          // Clear spill buffer when transitioning between short-circuit sequences.
-          // Different jump opcodes (41=JUMP_IF_FALSE for AND vs 42=JUMP_IF_TRUE for OR/NOR)
-          // indicate different short-circuit sequences.
-          if (lastJumpOp !== 41) {
-            spillTop = -1;
-          }
-          lastJumpOp = 41;
           break;
         }
       case OP_JUMP_IF_TRUE:
@@ -4482,13 +4515,11 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           if (!needsReconstruct(top) && slotVal(top) === true) {
             i += offset;
           }
-          // Clear spill buffer when transitioning between short-circuit sequences.
-          if (lastJumpOp !== 42) {
-            spillTop = -1;
-          }
-          lastJumpOp = 42;
           break;
         }
+      case OP_ENTER_SCOPE:
+        scopeStack[++scopeStackTop] = spillTop;
+        break;
       case OP_POP:
         {
           const popped = stack[stackTop--];
@@ -4503,15 +4534,19 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
       // AND/OR/NOR markers — collect the current stack top plus any residuals
       // that were spilled by OP_POP during the short-circuit sequence, then
       // apply the simplification logic.
+      //
+      // Each of these opcodes pops the scope base that was pushed by the
+      // matching OP_ENTER_SCOPE at the start of the short-circuit block. Only
+      // spill entries above that base (indices base+1..spillTop) belong to this
+      // scope; entries at 0..base belong to outer scopes and are preserved by
+      // restoring spillTop = base after draining.
       case OP_AND:
         {
           i++; // consume the operand count byte (unused — we use the spill buffer)
           const top = stack[stackTop--];
-          // Fast path: nothing was spilled — all non-top operands were concrete.
-          // The top is either a short-circuit false, the last true, or a lone residual.
-          // Push top directly — slotVal unwrapping happens at the final return point.
-          if (spillTop < 0) {
-            spillTop = -1;
+          const base = scopeStack[scopeStackTop--];
+          // Fast path: no entries were spilled in this scope.
+          if (spillTop === base) {
             if (!needsReconstruct(top)) {
               stack[++stackTop] = top;
             } else {
@@ -4520,10 +4555,8 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
             break;
           }
           const residuals = [];
-          // Drain spill buffer (residuals from earlier operands that were POP'd)
-          // Check if any spilled operand was false (dominates AND)
           let andDominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === false) {
               andDominated = true;
@@ -4533,8 +4566,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1; // clear spill buffer
-          // Include the stack top (last operand result)
+          spillTop = base; // restore outer scope
           if (!andDominated) {
             if (!needsReconstruct(top) && slotVal(top) === false) {
               andDominated = true;
@@ -4557,10 +4589,9 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
         {
           i++; // consume the operand count byte
           const top = stack[stackTop--];
-          // Fast path: nothing was spilled — all non-top operands were concrete.
-          // Push top directly — slotVal unwrapping happens at the final return point.
-          if (spillTop < 0) {
-            spillTop = -1;
+          const base = scopeStack[scopeStackTop--];
+          // Fast path: no entries were spilled in this scope.
+          if (spillTop === base) {
             if (!needsReconstruct(top)) {
               stack[++stackTop] = top;
             } else {
@@ -4570,7 +4601,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           }
           const residuals = [];
           let orDominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === true) {
               orDominated = true;
@@ -4580,7 +4611,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1;
+          spillTop = base; // restore outer scope
           if (!orDominated) {
             if (!needsReconstruct(top) && slotVal(top) === true) {
               orDominated = true;
@@ -4608,9 +4639,10 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
           // OP_NOT will pass through unchanged.
           i++; // consume the operand count byte
           const top = stack[stackTop--];
+          const base = scopeStack[scopeStackTop--];
           const residuals = [];
           let dominated = false;
-          for (let j = 0; j <= spillTop; j++) {
+          for (let j = base + 1; j <= spillTop; j++) {
             const v = spillBuf[j];
             if (!needsReconstruct(v) && slotVal(v) === true) {
               dominated = true;
@@ -4620,7 +4652,7 @@ function interpretSimplify(compiled, ctx, strictKeys, optionalKeys) {
               residuals.push(slotSrc(v));
             }
           }
-          spillTop = -1;
+          spillTop = base; // restore outer scope
           if (!dominated) {
             if (!needsReconstruct(top) && slotVal(top) === true) {
               dominated = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@briza/illogical",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.",
   "type": "module",
   "main": "./lib/illogical.cjs",
@@ -15,8 +15,8 @@
     "types/"
   ],
   "author": {
-    "name": "David Horak",
-    "email": "dhorak@briza.com"
+    "name": "Briza, Inc.",
+    "email": "dev@briza.com"
   },
   "license": "MIT",
   "scripts": {

package/readme.md

@@ -9,32 +9,32 @@
     <h3 align="center">illogical</h3>
   </div>
 
-[![build status](https://github.com/briza-insurance/illogical/actions/workflows/test.yml/badge.svg)](https://github.com/briza-insurance/illogical/actions?branch=master)
-[![npm version](https://badge.fury.io/js/@briza%2Fillogical.svg?icon=si%3Anpm)](https://badge.fury.io/js/@briza%2Fillogical)
-[![install size](https://packagephobia.com/badge?p=@briza/illogical)](https://packagephobia.com/result?p=@briza/illogical)
-![zero dependencies](https://img.shields.io/badge/0-dependencies-green)
-![npm downloads](https://img.shields.io/npm/dm/%40briza%2Fillogical)
-
-</div>
-
-<div align="center">
-<p>
-<br />
-JSON DSL for expressing and evaluating business rules. Underwriters use illogical to model business rules for their question sets, enabling distributors to render great user experiences.
-</p>
+  <p>
+  <strong>illogical</strong> is a JSON DSL (domain-specific language) for expressing and evaluating business rules in the insurance industry. Underwriters use illogical to model business rules for their question sets, enabling distributors to render great user experiences.
+  </p>
+
+  [![build status](https://github.com/briza-insurance/illogical/actions/workflows/test.yml/badge.svg)](https://github.com/briza-insurance/illogical/actions?branch=master)
+  [![npm version](https://badge.fury.io/js/@briza%2Fillogical.svg?icon=si%3Anpm)](https://badge.fury.io/js/@briza%2Fillogical)
+  [![install size](https://packagephobia.com/badge?p=@briza/illogical)](https://packagephobia.com/result?p=@briza/illogical)
+  ![zero dependencies](https://img.shields.io/badge/0-dependencies-green)
+  ![npm downloads](https://img.shields.io/npm/dm/%40briza%2Fillogical)
 </div>
 
 ---
 
-This project is designed such that business rules can be shared between the front-end and back-end, serialized in JSON.
+## 🚀 Getting Started
+
+Get up and running with illogical in just a few steps.
 
-## 🚀 Get Started
+### Installation
 
 ```sh
 # install illogical
 npm install @briza/illogical
 ```
 
+### Basic Usage
+
 ```js
 // Import the illogical engine
 import Engine from '@briza/illogical'
@@ -65,9 +65,11 @@ engine.evaluate(['==', '$age.(String)', '21'], ctx) // true
 engine.evaluate(['AND', ['>', '$age', 20], ['==', '$name', 'peter']]) // true
 ```
 
-## 🖼️ Resources
+## 📚 Documentation
+
+### Core Concepts
 
-Understand supported expressions:
+Explore the supported expressions and their usage:
 
 - [Comparison Expressions](./specs/comparison-expressions.md)
 - [Logical Expressions](./specs/logical-expressions.md)
@@ -75,19 +77,25 @@ Understand supported expressions:
 - [Evaluation Data Context](./specs/evaluation-data-context.md)
 - [Operand Types](./specs/operand-types.md)
 
-Learn about usages:
+### API Reference
+
+Learn how to use the engine and its methods:
 
 - [Evaluate](./specs/evaluate.md)
 - [Statement](./specs/statement.md)
 - [Parse](./specs/parse.md)
 - [Simplify](./specs/simplify.md)
 
+### Customization
+
 Customize the engine and the documentation:
 
 - [Engine Options](./specs/engine.md)
 - [Code Documentation](https://briza-insurance.github.io/illogical/index.html)
 
-Bytecode evaluation and debugging tools:
+### Development Tools
+
+For advanced usage like bytecode evaluation and debugging:
 
 - [Bytecode Evaluator](./specs/bytecode-evaluator.md)
 - [Debugger Tools](./specs/debugger-tools.md)

package/types/bytecode/opcodes.d.ts

@@ -49,3 +49,4 @@ export declare const OP_OR = 54;
 export declare const OP_NOR = 55;
 export declare const OP_IN_SCAN_REFS_CONST = 56;
 export declare const OP_NOT_IN_SCAN_REFS_CONST = 57;
+export declare const OP_ENTER_SCOPE = 58;

package/types/bytecode/refs.d.ts

@@ -71,3 +71,4 @@ export declare function resolveDynamic(key: string, dataType: DataType | undefin
  * (OP_OVERLAP_SCAN_REFS_CONST, OP_OR_AND_IN_CONST_2).
  */
 export declare function resolveCompactRef(ref: CompactRef, ctx: Context): Result;
+export declare function getKeyFromCompactRef(ref: CompactRef): string;