refactor(core)!: decouple regex compilation to support pluggable engines

Transform Sift into an engine-agnostic framework by introducing the `SiftEngine` SPI.
This architectural shift allows developers to swap the default JDK regex engine
with alternative implementations (e.g., RE2J for ReDoS protection) without breaking
the default zero-dependency behavior.

As a direct consequence of this decoupling:
- Implemented an internal feature-tracking system (Metadata) to enable engines to fail-fast on unsupported constructs.
- Fixed a Double-Checked Locking race condition in `BaseSiftPattern` caching.
- Standardized null-safety behavior (returning null) for replacement convenience methods.

BREAKING CHANGE: The terminal method `.sieve()` now returns a `SiftCompiledPattern` abstraction instead of a `java.util.regex.Pattern`.

Author: Mirkoddd

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

@@ -1,14 +1,33 @@
+/*
+ * 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.SiftContext;
 import com.mirkoddd.sift.core.dsl.SiftPattern;
+import com.mirkoddd.sift.core.engine.RegexFeature;
 
+import java.util.Collections;
+import java.util.EnumSet;
 import java.util.Set;
 
 /**
  * Decorator that wraps a pattern in an atomic group (?>...).
  */
-class AtomicPattern<Ctx extends SiftContext> extends BaseSiftPattern<Ctx> implements PatternMetadata {
+class AtomicPattern<Ctx extends SiftContext> extends BaseSiftPattern<Ctx> {
+
     private final SiftPattern<Ctx> inner;
 
     AtomicPattern(SiftPattern<Ctx> inner) {
@@ -17,24 +36,33 @@ class AtomicPattern<Ctx extends SiftContext> extends BaseSiftPattern<Ctx> implem
 
     @Override
     protected String buildRegex() {
-        final String atomicOpen = "(?>";
-        final String atomicClose = ")";
-        return atomicOpen + inner.shake() + atomicClose;
+        return "(?>" + inner.shake() + ")";
+    }
+
+    @Override
+    protected Set<RegexFeature> buildFeatures() {
+        Set<RegexFeature> features = EnumSet.of(RegexFeature.ATOMIC_GROUP);
+
+        if (inner instanceof PatternMetadata) {
+            features.addAll(((PatternMetadata) inner).getInternalUsedFeatures());
+        }
+
+        return Collections.unmodifiableSet(features);
     }
 
     @Override
     public Set<String> getInternalRegisteredGroups() {
         if (inner instanceof PatternMetadata) {
             return ((PatternMetadata) inner).getInternalRegisteredGroups();
         }
-        return java.util.Collections.emptySet();
+        return Collections.emptySet();
     }
 
     @Override
     public Set<String> getInternalRequiredBackreferences() {
         if (inner instanceof PatternMetadata) {
             return ((PatternMetadata) inner).getInternalRequiredBackreferences();
         }
-        return java.util.Collections.emptySet();
+        return Collections.emptySet();
     }
 }

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

@@ -1,22 +1,46 @@
+/*
+ * 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.SiftContext;
 import com.mirkoddd.sift.core.dsl.SiftPattern;
+import com.mirkoddd.sift.core.engine.RegexFeature;
+import com.mirkoddd.sift.core.engine.SiftCompiledPattern;
+import com.mirkoddd.sift.core.engine.SiftEngine;
+
+import java.util.Collections;
 import java.util.Objects;
-import java.util.regex.Pattern;
+import java.util.Set;
 
 /**
  * Internal foundation for all Sift patterns.
  * <p>
  * This class centralizes the <b>Double-Checked Locking</b> logic for thread-safe caching
- * of both the regex string and the compiled Pattern. It also implements the
- * com.mirkoddd.sift.core.dsl.SiftInternalSealer interface to prevent unauthorized
- * external implementations.
+ * of the generated regex string and its associated structural features.
+ * <p>
+ * By completely decoupling the string generation from the runtime execution engine,
+ * this core class implements the Dependency Inversion Principle, allowing Sift
+ * to act as a framework-agnostic regex builder.
+ *
+ * @param <Ctx> The specific context type for state machine validation.
  */
-abstract class BaseSiftPattern<Ctx extends SiftContext> implements SiftPattern<Ctx> {
+abstract class BaseSiftPattern<Ctx extends SiftContext> implements SiftPattern<Ctx>, PatternMetadata {
 
     private volatile String cachedRegex = null;
-    private volatile Pattern cachedPattern = null;
+    private volatile Set<RegexFeature> cachedFeatures = null;
 
     @Override
     public final Object ___internal_lock___() {
@@ -28,30 +52,62 @@ public final String shake() {
         if (cachedRegex == null) {
             synchronized (this) {
                 if (cachedRegex == null) {
-                    String raw = buildRegex();
-                    try {
-                        cachedPattern = Pattern.compile(raw);
-                        cachedRegex = raw;
-                    } catch (java.util.regex.PatternSyntaxException e) {
-                        throw new IllegalStateException("Sift generated an invalid regex pattern: " + raw, e);
-                    }
+                    Set<RegexFeature> computedFeatures = Collections.unmodifiableSet(buildFeatures());
+                    String computedRegex = buildRegex();
+                    this.cachedFeatures = computedFeatures;
+                    this.cachedRegex = computedRegex;
                 }
             }
         }
         return cachedRegex;
     }
 
     @Override
-    public final Pattern sieve() {
+    public final SiftCompiledPattern sieveWith(SiftEngine engine) {
         shake();
-        return cachedPattern;
+        return engine.compile(cachedRegex, cachedFeatures);
+    }
+
+    @Override
+    public Set<String> getInternalRegisteredGroups() {
+        // Default implementation: empty.
+        // Overridden by complex builders (like SiftConnector) that manage state.
+        return Collections.emptySet();
+    }
+
+    @Override
+    public Set<String> getInternalRequiredBackreferences() {
+        // Default implementation: empty.
+        // Overridden by complex builders.
+        return Collections.emptySet();
+    }
+
+    @Override
+    public Set<RegexFeature> getInternalUsedFeatures() {
+        shake();
+        return buildFeatures();
     }
 
     /**
-     * Implemented by subclasses to define the specific regex logic.
+     * Implemented by subclasses to define the specific regex string generation logic.
+     *
+     * @return The raw regular expression string.
      */
     protected abstract String buildRegex();
 
+    /**
+     * Implemented by subclasses to report advanced features (e.g., lookarounds, backreferences)
+     * used during the pattern assembly.
+     * <p>
+     * The default implementation returns an empty set. Complex pattern builders should
+     * override this method to accurately reflect their structural requirements.
+     *
+     * @return A set of features used by this specific pattern.
+     */
+    protected Set<RegexFeature> buildFeatures() {
+        return Collections.emptySet();
+    }
+
     @Override
     public final SiftPattern<Ctx> preventBacktracking() {
         return new AtomicPattern<>(this);

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

@@ -17,14 +17,17 @@
 
 import com.mirkoddd.sift.core.dsl.Composable;
 import com.mirkoddd.sift.core.dsl.SiftPattern;
+import com.mirkoddd.sift.core.engine.RegexFeature;
 
 import java.util.Collections;
+import java.util.EnumSet;
 import java.util.HashSet;
 import java.util.Set;
 
 /**
  * Internal Buffer and String manipulator for Regex generation.
- * Handles the low-level string concatenation, character escaping, and class flushing.
+ * Handles the low-level string concatenation, character escaping, class flushing,
+ * and tracking of advanced regex features for cross-engine compatibility.
  */
 class PatternAssembler {
 
@@ -46,6 +49,7 @@ private enum QuantifierModifier {
     private final Set<String> registeredGroups = new HashSet<>();
     private final Set<String> requiredBackreferences = new HashSet<>();
     private boolean containsAbsoluteAnchor = false;
+    private final EnumSet<RegexFeature> usedFeatures = EnumSet.noneOf(RegexFeature.class);
 
     PatternAssembler() {
     }
@@ -56,6 +60,7 @@ private enum QuantifierModifier {
             mainPattern.append(flag.getSymbol());
         }
         mainPattern.append(RegexSyntax.GROUP_CLOSE);
+        registerFeature(RegexFeature.INLINE_FLAGS);
     }
 
     Set<String> getRegisteredGroups() {
@@ -70,6 +75,14 @@ public boolean isContainsAbsoluteAnchor() {
         return containsAbsoluteAnchor;
     }
 
+    Set<RegexFeature> getUsedFeatures() {
+        return Collections.unmodifiableSet(usedFeatures);
+    }
+
+    void registerFeature(RegexFeature feature) {
+        this.usedFeatures.add(feature);
+    }
+
     void setQuantifier(String quantifier) {
         this.currentQuantifier = quantifier;
     }
@@ -125,6 +138,8 @@ void addNamedCapture(NamedCapture group) {
 
         extractAndCheckGroupsAndRequirements(group.getPattern(), group.getName());
 
+        registerFeature(RegexFeature.NAMED_CAPTURE);
+
         mainPattern.append(RegexSyntax.NAMED_GROUP_OPEN)
                 .append(group.getName())
                 .append(RegexSyntax.NAMED_GROUP_NAME_CLOSE)
@@ -135,6 +150,8 @@ void addNamedCapture(NamedCapture group) {
     void addBackreference(NamedCapture group) {
         requiredBackreferences.add(group.getName());
 
+        registerFeature(RegexFeature.BACKREFERENCE);
+
         mainPattern.append(RegexSyntax.NAMED_BACKREFERENCE_OPEN)
                 .append(group.getName())
                 .append(RegexSyntax.NAMED_BACKREFERENCE_CLOSE);
@@ -214,6 +231,8 @@ private void extractAndCheckGroupsAndRequirements(SiftPattern<?> pattern, String
         }
 
         requiredBackreferences.addAll(getIncomingBackreferences(pattern));
+
+        usedFeatures.addAll(getIncomingFeatures(pattern));
     }
 
     private static Set<String> getIncomingGroups(SiftPattern<?> pattern) {
@@ -230,6 +249,13 @@ private static Set<String> getIncomingBackreferences(SiftPattern<?> pattern) {
         return Collections.emptySet();
     }
 
+    private static Set<RegexFeature> getIncomingFeatures(SiftPattern<?> pattern) {
+        if (pattern instanceof PatternMetadata) {
+            return ((PatternMetadata) pattern).getInternalUsedFeatures();
+        }
+        return Collections.emptySet();
+    }
+
     void addWordBoundary() {
         flush();
         mainPattern.append(RegexSyntax.WORD_BOUNDARY);
@@ -308,6 +334,7 @@ PatternAssembler copy() {
         clone.registeredGroups.addAll(this.registeredGroups);
         clone.requiredBackreferences.addAll(this.requiredBackreferences);
         clone.containsAbsoluteAnchor = this.containsAbsoluteAnchor;
+        clone.usedFeatures.addAll(this.usedFeatures);
         return clone;
     }
 

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

@@ -1,5 +1,7 @@
 package com.mirkoddd.sift.core;
 
+import com.mirkoddd.sift.core.engine.RegexFeature;
+
 import java.util.Set;
 
 /**
@@ -9,4 +11,5 @@
 interface PatternMetadata {
     Set<String> getInternalRegisteredGroups();
     Set<String> getInternalRequiredBackreferences();
+    Set<RegexFeature> getInternalUsedFeatures();
 }

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

@@ -16,6 +16,7 @@
 package com.mirkoddd.sift.core;
 
 import com.mirkoddd.sift.core.dsl.*;
+import com.mirkoddd.sift.core.engine.RegexFeature;
 
 import java.util.Objects;
 
@@ -111,6 +112,7 @@ public static Connector<Fragment> fromWordBoundary() {
      */
     public static Quantifier<Root> fromPreviousMatchEnd() {
         PatternAssembler assembler = new PatternAssembler();
+        assembler.registerFeature(RegexFeature.PREVIOUS_MATCH_ANCHOR);
         assembler.addAnchor(RegexSyntax.PREVIOUS_MATCH_END);
         return new SiftQuantifier<>(assembler);
     }
@@ -227,6 +229,7 @@ public Connector<Root> fromWordBoundary() {
          */
         public Quantifier<Root> fromPreviousMatchEnd() {
             PatternAssembler assembler = new PatternAssembler(flags);
+            assembler.registerFeature(RegexFeature.PREVIOUS_MATCH_ANCHOR);
             assembler.addAnchor(RegexSyntax.PREVIOUS_MATCH_END);
             return new SiftQuantifier<>(assembler);
         }

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

@@ -16,6 +16,7 @@
 package com.mirkoddd.sift.core;
 
 import com.mirkoddd.sift.core.dsl.*;
+import com.mirkoddd.sift.core.engine.RegexFeature;
 
 import java.util.Objects;
 import java.util.Set;
@@ -74,6 +75,7 @@ public Connector<Ctx> followedByAssertion(SiftPattern<Assertion> assertion) {
         Objects.requireNonNull(assertion, "Assertion cannot be null");
 
         PatternAssembler next = assembler.copy();
+        next.registerFeature(RegexFeature.LOOKAHEAD);
         next.addPattern(assertion);
         return new SiftConnector<>(next);
     }
@@ -113,6 +115,7 @@ public Connector<Ctx> precededByAssertion(SiftPattern<Assertion> assertion) {
         Objects.requireNonNull(assertion, "Assertion cannot be null");
 
         PatternAssembler next = assembler.copy();
+        next.registerFeature(RegexFeature.LOOKBEHIND);
         next.prependPattern(assertion);
         return new SiftConnector<>(next);
     }
@@ -176,4 +179,9 @@ public Set<String> getInternalRegisteredGroups() {
     public Set<String> getInternalRequiredBackreferences() {
         return assembler.getRequiredBackreferences();
     }
+
+    @Override
+    public Set<RegexFeature> getInternalUsedFeatures() {
+        return assembler.getUsedFeatures();
+    }
 }