feat(core): implement robust recursion engine for nested structures

- Added private recursive() engine for safe regex unrolling (depth 2-10).
- Introduced Delimiter contract to enforce structural symmetry (Dyck languages).
- Implemented NestingAssembler to hide recursion complexity and provide a safe DSL.
- Added comprehensive SiftNestingTest suite including JSON parsing and exception handling.

Author: Mirkoddd

sift-core/src/main/java/com/mirkoddd/sift/core/Delimiter.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 Mirko Dimartino
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.mirkoddd.sift.core;
+
+import java.util.Objects;
+
+/**
+ * Represents a symmetric pair of delimiters used to define boundaries for nested structures.
+ * <p>
+ * In formal language theory (specifically Dyck languages), balanced structures require a strict
+ * 1-to-1 relationship between an opening symbol and a closing symbol. This class enforces that
+ * contract, ensuring that developers cannot accidentally create asymmetric recursive patterns
+ * (e.g., opening with a parenthesis but closing with a square bracket).
+ * </p>
+ * <p>
+ * Standard symmetric pairs are provided as immutable constants. For domain-specific parsers, 
+ * custom boundaries can be generated via the {@link #custom(String, String)} factory method.
+ * </p>
+ */
+public final class Delimiter {
+
+    private final String open;
+    private final String close;
+
+    /**
+     * Standard parentheses pair: {@code (} and {@code )}.
+     */
+    public static final Delimiter PARENTHESES = new Delimiter("(", ")");
+
+    /**
+     * Standard square brackets pair: {@code [} and {@code ]}.
+     */
+    public static final Delimiter BRACKETS = new Delimiter("[", "]");
+
+    /**
+     * Standard curly braces pair: {@code \{} and {@code \}}.
+     */
+    public static final Delimiter BRACES = new Delimiter("{", "}");
+
+    /**
+     * Standard angle brackets (chevrons) pair: {@code <} and {@code >}.
+     */
+    public static final Delimiter CHEVRONS = new Delimiter("<", ">");
+
+    /**
+     * Internal constructor to enforce symmetry.
+     *
+     * @param open  The exact literal string that opens the structure.
+     * @param close The exact literal string that closes the structure.
+     */
+    private Delimiter(String open, String close) {
+        this.open = open;
+        this.close = close;
+    }
+
+    /**
+     * Factory method to create a custom symmetric pair for domain-specific nested structures
+     * (e.g., HTML tags, multi-character comment blocks like {@code /*} and {@code *\/}).
+     *
+     * @param open  The exact literal string that opens the structure. Cannot be null.
+     * @param close The exact literal string that closes the structure. Cannot be null.
+     * @return A new {@link Delimiter} instance representing the symmetric contract.
+     * @throws NullPointerException if either parameter is null.
+     */
+    public static Delimiter custom(String open, String close) {
+        return new Delimiter(
+                Objects.requireNonNull(open, "Opening delimiter cannot be null."),
+                Objects.requireNonNull(close, "Closing delimiter cannot be null.")
+        );
+    }
+
+    /**
+     * Retrieves the opening boundary literal.
+     *
+     * @return The literal string that triggers a new nesting level.
+     */
+    public String open() {
+        return open;
+    }
+
+    /**
+     * Retrieves the closing boundary literal.
+     *
+     * @return The literal string that terminates the current nesting level.
+     */
+    public String close() {
+        return close;
+    }
+}

sift-core/src/main/java/com/mirkoddd/sift/core/NestingAssembler.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2026 Mirko Dimartino
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.mirkoddd.sift.core;
+
+import com.mirkoddd.sift.core.dsl.Fragment;
+import com.mirkoddd.sift.core.dsl.SiftPattern;
+import java.util.Objects;
+
+import static com.mirkoddd.sift.core.SiftPatterns.anyOf;
+import static com.mirkoddd.sift.core.SiftPatterns.literal;
+import static com.mirkoddd.sift.core.SiftPatterns.recursive;
+
+/**
+ * A fluent builder designed to safely construct recursive nested structures.
+ * <p>
+ * It enforces the use of a symmetric {@link Delimiter} pair and handles the
+ * complex injection of the 'self' recursive reference, shielding the developer
+ * from logic errors and unbalanced grammar definitions.
+ * </p>
+ */
+public final class NestingAssembler {
+    private final int depth;
+    private Delimiter pair;
+
+    NestingAssembler(int depth) {
+        this.depth = depth;
+    }
+
+    /**
+     * Defines the symmetric boundaries for this nested structure.
+     *
+     * @param pair The {@link Delimiter} pair (e.g., {@link Delimiter#PARENTHESES}).
+     * @return This builder instance for method chaining.
+     * @throws NullPointerException if the pair is null.
+     */
+    public NestingAssembler using(Delimiter pair) {
+        this.pair = Objects.requireNonNull(pair, "Delimiter pair cannot be null.");
+        return this;
+    }
+
+    /**
+     * Finalizes the nested structure by defining what content is allowed inside.
+     * <p>
+     * The builder automatically wraps the provided content pattern (and the hidden
+     * recursive call to itself) within the specified opening and closing delimiters.
+     * Both delimiters are strictly treated as literal strings to prevent regex injection.
+     * </p>
+     *
+     * @param content The pattern representing the allowed content inside the structure.
+     * @return A deeply nested fragment capable of parsing balanced structures.
+     * @throws NullPointerException  if the content is null.
+     * @throws IllegalStateException if {@code using()} was not called prior to this method.
+     */
+    public SiftPattern<Fragment> containing(SiftPattern<Fragment> content) {
+        if (this.pair == null) {
+            throw new IllegalStateException(
+                    "A Delimiter pair must be specified using .using() before defining content."
+            );
+        }
+        Objects.requireNonNull(content, "Content pattern cannot be null.");
+
+        // THE SECRET SAUCE:
+        // We invoke the private unrolling engine. The 'self' parameter representing
+        // the recursive call is injected as an alternative to the base content,
+        // strictly bounded by the literal opening and closing delimiters.
+        return recursive(depth, self ->
+                Sift.fromAnywhere()
+                        .of(literal(pair.open()))
+                        .then()
+                        .zeroOrMore().of(anyOf(content, self))
+                        .followedBy(literal(pair.close()))
+        );
+    }
+}
+

sift-core/src/main/java/com/mirkoddd/sift/core/SiftPatterns.java

@@ -22,6 +22,7 @@
 import com.mirkoddd.sift.core.dsl.SiftPattern;
 
 import java.util.Objects;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
 /**
@@ -343,6 +344,69 @@ public static SiftPattern<Fragment> anythingBut(String chars) {
         });
     }
 
+    /**
+     * Initiates the creation of a safely nested recursive pattern.
+     * <p>
+     * This factory method returns a fluent {@link NestingAssembler} that guarantees
+     * structural symmetry by forcing the use of a valid {@link Delimiter} pair.
+     * </p>
+     *
+     * @param depth The maximum nesting depth to unroll (must be between 2 and 10).
+     * @return A {@link NestingAssembler} to configure the delimiter and content.
+     */
+    public static NestingAssembler nesting(int depth) {
+        return new NestingAssembler(depth);
+    }
+
+    /**
+     * Internal unrolling engine that emulates Regular Expression recursion.
+     * <p>
+     * Since Java's native {@link java.util.regex.Pattern} lacks support for true
+     * PCRE-style recursion (like {@code (?R)}), this method achieves a similar result
+     * by functionally unrolling the pattern definition from the inside out.
+     * </p>
+     * <p>
+     * <b>JVM Safety Bounds:</b> The depth is strictly clamped between 2 and 10.
+     * Compiling deeply nested regex strings grows exponentially and will quickly trigger
+     * a {@code StackOverflowError} within the JVM's regex compiler. A depth of 10 is
+     * mathematically vast for real-world structured data.
+     * </p>
+     *
+     * @param maxDepth   The maximum number of nesting levels to unroll (must be between 2 and 10).
+     * @param definition A functional block where the parameter represents the recursive
+     * call to the pattern itself (the 'self' reference).
+     * @return A deeply nested fragment capable of parsing recursive structures up to {@code maxDepth}.
+     * @throws IllegalArgumentException if {@code maxDepth} is outside the safe bounds [2, 10].
+     * @throws NullPointerException     if the {@code definition} function is null.
+     */
+    static SiftPattern<Fragment> recursive(
+            int maxDepth,
+            Function<SiftPattern<Fragment>, SiftPattern<Fragment>> definition) {
+
+        if (maxDepth < 2 || maxDepth > 10) {
+            throw new IllegalArgumentException(
+                    "Recursion depth must be strictly between 2 and 10 to ensure JVM stability and prevent StackOverflowErrors."
+            );
+        }
+        Objects.requireNonNull(definition, "Recursive definition cannot be null.");
+
+        // BASE CASE (The bottom of the Matryoshka):
+        // If the parsing engine attempts to go deeper than maxDepth, it hits this empty negative lookahead.
+        // In Regex mathematics, (?!) is a logical contradiction that is guaranteed to ALWAYS fail.
+        // This ensures the regex stops safely instead of breaking unexpectedly.
+        SiftPattern<Fragment> current = memoize(() -> "(?!)");
+
+        // UNROLLING (Inside-Out Injection):
+        // We build the nested structure by applying the function repeatedly.
+        // At each iteration, the previously built layer is injected as the 'self' parameter
+        // for the next layer up, effectively unrolling the recursion.
+        for (int i = 0; i < maxDepth; i++) {
+            current = definition.apply(current);
+        }
+
+        return current;
+    }
+
     /**
      * Memoizes a pattern generation using a supplier, making it generic so it can
      * safely produce both Fragments and Assertions without unchecked casts.