fix(core): don't inline-interpolate into a fuzzy-match marker

A match RHS like `'#[] ##(itemSchema)'` reached processInlineEmbedded
because it contains `#(`. The inline pass evaluated the embedded schema
to a Map and stringified it back into the marker, corrupting it — the
match engine then threw `expected: [R_CURLY]`.

v1 never inline-interpolated (only whole-value `#(...)` / `##(...)`
strings were processed), so a `#`-leading marker survived verbatim to
the match engine, where the `#[]` each-schema path resolved the bare /
embedded reference. Mirror that: processEmbeddedString now leaves any
`#`-leading string intact and defers `#(...)` / `##(...)` resolution to
the match engine.

The documented shortcut is the bare reference `'#[] schema'`; `'#[]
#(schema)'` is a redundant synonym. The fix simply stops the
undocumented embedded variants from parse-erroring. Adds tests pinning
the canonical form, the synonym equivalence, and the whole-array vs
per-element nullability distinctions.

fixes #2893

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ptrthomas

karate-core/src/main/java/io/karatelabs/core/StepExecutor.java

@@ -3072,6 +3072,16 @@ private Object processEmbeddedString(String str) {
                 return str;
             }
         }
+        // A string that *starts* with '#' is a fuzzy-match marker, not free text —
+        // e.g. '#string', '#[] schema', '#[] ##(itemSchema)'. Such a marker may embed
+        // a #(...) / ##(...) expression that the match engine resolves later (the #[]
+        // each-schema path). Inline-interpolating here would stringify the resolved
+        // schema into the marker and corrupt it. v1 never inline-interpolated (it only
+        // processed whole-value #(...)/##(...) strings), so markers survived verbatim;
+        // mirror that and leave the marker intact for the match engine.
+        if (str.startsWith("#")) {
+            return str;
+        }
         // Check for embedded expressions within a larger string
         // e.g., "Hello #(name)!" or "Value: ##(optional)"
         if (str.contains("#(")) {

karate-core/src/test/java/io/karatelabs/core/StepMatchTest.java

@@ -732,4 +732,85 @@ void testMatchSchemaTemplateAcrossCallBoundary() {
         assertPassed(sr);
     }
 
+    // ========== Array-marker + schema-reference shortcut ('#[] schema') ==========
+    // The documented v1 shortcut is the BARE reference: '#[] schema' — after the
+    // array marker comes a raw expression (variable, property path, function call)
+    // that the match engine evaluates to the per-element schema. The '#(schema)'
+    // embedded-expression wrapper is a redundant synonym for the bare form.
+    //
+    // v1 never inline-interpolated embedded expressions (only whole-value #(...) /
+    // ##(...) strings were processed), so a marker like '#[] ##(schema)' survived
+    // verbatim to the match engine. v2 added inline interpolation, which used to
+    // stringify the resolved schema into the marker and corrupt it (parse error).
+    // processEmbeddedString now leaves any '#'-leading marker intact, restoring the
+    // behavior and keeping the marker well-formed for the match engine.
+
+    @Test
+    void testArrayMarkerBareSchemaReference() {
+        // Canonical / recommended form.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: [ { id: 1, name: 'a' }, { id: 2, name: 'b' } ] }
+            * match response == { items: '#[] itemSchema' }
+            """);
+        assertPassed(sr);
+    }
+
+    @Test
+    void testArrayMarkerEmbeddedSchemaReferenceIsSynonymOfBare() {
+        // '#[] #(schema)' behaves identically to '#[] schema' — the #(...) adds
+        // nothing here. Pinned so the embedded form no longer throws a parse error.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: [ { id: 1, name: 'a' }, { id: 2, name: 'b' } ] }
+            * match response == { items: '#[] #(itemSchema)' }
+            """);
+        assertPassed(sr);
+    }
+
+    @Test
+    void testOptionalArrayMarkerAllowsNullArray() {
+        // '##[]' makes the whole array optional — a null (or absent) value passes.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: null }
+            * match response == { items: '##[] itemSchema' }
+            """);
+        assertPassed(sr);
+    }
+
+    @Test
+    void testArrayMarkerRequiresPresentArray() {
+        // '#[]' (single hash) requires the array to be present — null fails.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: null }
+            * match response == { items: '#[] itemSchema' }
+            """);
+        assertFailed(sr);
+    }
+
+    @Test
+    void testPerElementOptionalSchemaAllowsNullElement() {
+        // The only thing the embedded form can express that the bare form can't:
+        // a per-element '##(schema)' lets an individual array element be null.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: [ { id: 1, name: 'a' }, null ] }
+            * match response == { items: '#[] ##(itemSchema)' }
+            """);
+        assertPassed(sr);
+    }
+
+    @Test
+    void testPerElementRequiredSchemaRejectsNullElement() {
+        // Complement of the above: bare / '#(schema)' per-element does NOT allow nulls.
+        ScenarioRuntime sr = run("""
+            * def itemSchema = { id: '#number', name: '#string' }
+            * def response = { items: [ { id: 1, name: 'a' }, null ] }
+            * match response == { items: '#[] itemSchema' }
+            """);
+        assertFailed(sr);
+    }
+
 }