Add caching: the Spring cache abstraction, keys, eviction timing and the self-invocation trap

A Spring Boot 4.1.1 module whose test suite is the evidence for the article: 19 tests
producing 22 transcripts under docs/output/, plus 12 documentation chapters.

Findings the build pins:
- @EnableCaching has no exposeProxy attribute; the widely-copied
  @EnableCaching(exposeProxy = true) does not compile.
- Two methods sharing a cache name and an argument type share a key space, and one
  silently serves the other's answers.
- beforeInvocation = true is NOT deferred by TransactionAwareCacheManagerProxy on
  7.0.9 - doEvict picks evictIfPresent, which the decorator does not intercept.
- Four of five invalid declarations start a clean context and throw at the first call.
- Caffeine on the classpath silently displaces the simple provider.

caching/scripts/capture-bytecode.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Disassembles the two methods that decide whether a beforeInvocation=true eviction is deferred.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+M2="${HOME}/.m2/repository/org/springframework"
+V=$(mvn -B -q help:evaluate -Dexpression=spring-framework.version -DforceStdout 2>/dev/null | tail -1)
+CTX="${M2}/spring-context/${V}/spring-context-${V}.jar"
+CS="${M2}/spring-context-support/${V}/spring-context-support-${V}.jar"
+
+{
+  echo "# Why beforeInvocation=true is not deferred by TransactionAwareCacheManagerProxy"
+  echo
+  echo "\$ javap -c -p org.springframework.cache.interceptor.AbstractCacheInvoker   # spring-context-${V}.jar"
+  javap -c -p -cp "$CTX" org.springframework.cache.interceptor.AbstractCacheInvoker \
+    | grep -v '^Picked up' | awk '/protected void doEvict/,/^$/' | head -14
+  echo
+  echo "\$ javap -c -p org.springframework.cache.transaction.TransactionAwareCacheDecorator   # spring-context-support-${V}.jar"
+  javap -c -p -cp "$CS" org.springframework.cache.transaction.TransactionAwareCacheDecorator \
+    | grep -v '^Picked up' | awk '/public void evict\(java.lang.Object\)/,/^$/' | head -14
+  javap -c -p -cp "$CS" org.springframework.cache.transaction.TransactionAwareCacheDecorator \
+    | grep -v '^Picked up' | awk '/public boolean evictIfPresent/,/^$/' | head -8
+  echo
+  echo "doEvict(cache, key, true)  -> Cache.evictIfPresent  -> straight to the target cache"
+  echo "doEvict(cache, key, false) -> Cache.evict           -> registerSynchronization, runs after commit"
+  echo
+  echo "spring-framework#23192 reported beforeInvocation=true being swallowed by the"
+  echo "transaction-aware decorator. On ${V} it is not: the immediate path uses a method"
+  echo "the decorator does not intercept. Note also that the decorator ships in"
+  echo "spring-context-support, not spring-context."
+} > docs/output/22-decorator-bytecode.txt
+echo "wrote docs/output/22-decorator-bytecode.txt"

caching/scripts/capture-diagnostics.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Starts the application on the simple provider, exercises a few cached methods, and dumps the
+# live contents of every cache through /diag/caches.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+PORT=8080
+PIDFILE=/tmp/caching-demo.pid
+
+mvn -B -q -DskipTests package
+nohup java -jar target/caching-1.0.0.jar \
+  --spring.cache.type=simple --server.port=${PORT} > /tmp/caching-demo.log 2>&1 &
+echo $! > "$PIDFILE"
+
+for _ in $(seq 1 60); do
+  curl -sf "http://localhost:${PORT}/actuator/health" >/dev/null 2>&1 && break
+  sleep 1
+done
+
+{
+  echo "# The live contents of every cache, keys included"
+  echo
+  echo "\$ curl -s localhost:${PORT}/diag/warm"
+  curl -s "http://localhost:${PORT}/diag/warm"
+  echo
+  echo
+  echo "\$ curl -s localhost:${PORT}/diag/caches | jq ."
+  curl -s "http://localhost:${PORT}/diag/caches" | python3 -m json.tool
+} > docs/output/23-diagnostics.txt
+
+kill "$(cat "$PIDFILE")" 2>/dev/null || true
+rm -f "$PIDFILE"
+echo "wrote docs/output/23-diagnostics.txt"

caching/scripts/run-all.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Regenerates every file under docs/output/.
+#
+#   ./scripts/run-all.sh
+#
+# Needs a JDK 25 and Maven 3.9. Everything except the two javap transcripts and the live
+# diagnostics dump comes out of the test suite, which is the point: the numbers in the article
+# are assertions that fail the build if they stop being true.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+echo "== test suite (transcripts 01-20)"
+mvn -B test
+
+echo "== javap transcripts (22)"
+./scripts/capture-bytecode.sh
+
+echo "== live diagnostics endpoint (23)"
+./scripts/capture-diagnostics.sh
+
+echo
+echo "docs/output:"
+ls -1 docs/output