[api][java] Substitute prompt placeholders in a single pass

[Zhuoxi2000]

Linked issue: #907

Purpose of change

LocalPrompt.format previously applied String.replace once per variable. This meant that substituted values could be interpreted again as placeholders, making the result dependent on map iteration order and allowing a value such as {secret} to expand into another variable's value.

This change scans the original template once and replaces only placeholders found in that template. Unknown placeholders are left untouched, and substituted values are inserted literally rather than processed again.

This also restores parity with Python's SafeFormatter, which already performs substitution in a single pass.

Tests

Added regression tests in both Java and Python covering:

• substituted values are not re-expanded;
• values cannot inject another variable;
• the same behavior through both the string and message formatting paths.

The new Java tests fail on main and pass with this change.

Validation:

• mvn -pl api test: 276 run, 0 failures, 9 skipped
• Python api/tests/test_prompt.py: 10 passed
• mvn -pl api spotless:check: clean
• ruff check: clean
• ruff format --check: clean

API

No public API signatures are changed. This only fixes placeholder substitution behavior for values that themselves contain {...} tokens matching another provided variable. Normal template formatting is unaffected.

Documentation

• doc-needed
• doc-not-needed
• doc-included

[Zhuoxi2000]

the only failing check is it-python [flink-1.20], which looks like a flake unrelated to this change.

could a committer rerun the failed job when convenient? Happy to investigate if it reproduces. Thanks!

[weiqingy]

One small optional thought: The switch from String.replace to appendReplacement quietly changes how a value's own characters are treated: String.replace inserted values literally, whereas appendReplacement reads $ as a group reference and \ as an escape — so quoteReplacement(...) here is doing real load-bearing work (a value like "$5.00" would otherwise throw). The new tests all use $-free values, so nothing currently locks that behavior in. Would it be worth one assertion with a value containing a $ (say {price} -> "$5.00 (was $9)") so a future refactor can't drop the quoteReplacement call unnoticed? Something like this, if useful:

@Test
@DisplayName("Values containing $ and \\ are inserted literally")
void testValueWithRegexReplacementChars() {
    Prompt prompt = Prompt.fromText("Price: {price}");
    Map<String, String> vars = new HashMap<>();
    vars.put("price", "$5.00 (was $9) \\ end");
    assertEquals("Price: $5.00 (was $9) \\ end", prompt.formatString(vars));
}

Python's re.sub with a function replacement has no $/\ sensitivity, so a mirror Python test is optional — this one is really a Java-only guard.