Add TestDataDependency for creator dependencies

Replaces the hand-rolled field-plus-sameXyz-flag memoization in
creators: fixed, shared, and per-item modes in one holder. resolve() is
safe under parallel item creation - a shared value is created exactly
once, per-item creation stays unsynchronized.

Author: SirCotare

src/main/java/it/aboutbits/springboot/testing/testdata/base/TestDataDependency.java

@@ -0,0 +1,64 @@
+package it.aboutbits.springboot.testing.testdata.base;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.function.Supplier;
+
+/// A dependency of a test-data creator that each created item needs a value for.
+/// Three modes, chosen while the creator is being configured:
+///
+///   - fixed:    [#set(Object)] — every item uses the explicitly provided value (`withXyz(id)`)
+///   - shared:   [#share()] — the first resolution creates the value, every later one reuses it
+///               (`sameXyz()`, or dependencies that are always shared across the items)
+///   - per item: neither — every resolution creates a fresh value (the default)
+///
+/// [#resolve(Supplier)] is safe under parallel item creation: a shared value is created exactly
+/// once (competing items wait for it), while per-item creation runs unsynchronized. The
+/// configuration methods ([#set(Object)], [#share()]) belong to the builder phase and must not
+/// be called once item creation has started.
+@NullMarked
+public final class TestDataDependency<T> {
+    private boolean shared;
+    private @Nullable T value;
+
+    private TestDataDependency(boolean shared) {
+        this.shared = shared;
+    }
+
+    public static <T> TestDataDependency<T> perItem() {
+        return new TestDataDependency<>(false);
+    }
+
+    public static <T> TestDataDependency<T> shared() {
+        return new TestDataDependency<>(true);
+    }
+
+    public synchronized void set(T value) {
+        this.value = value;
+        this.shared = true;
+    }
+
+    public synchronized void share() {
+        this.shared = true;
+    }
+
+    /// True once a value is fixed or has been resolved — used by creators whose dependency is
+    /// optional, to decide between "absent" and "resolve".
+    public synchronized boolean isSet() {
+        return value != null;
+    }
+
+    public T resolve(Supplier<T> creator) {
+        if (!shared) {
+            return creator.get();
+        }
+
+        synchronized (this) {
+            if (value == null) {
+                value = creator.get();
+            }
+            return value;
+        }
+    }
+}

src/test/java/it/aboutbits/springboot/testing/testdata/base/TestDataDependencyTest.java

@@ -0,0 +1,87 @@
+package it.aboutbits.springboot.testing.testdata.base;
+
+import org.jspecify.annotations.NullMarked;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@NullMarked
+class TestDataDependencyTest {
+    @Test
+    void perItem_resolvesFreshValueEveryTime() {
+        var creations = new AtomicInteger();
+        var dependency = TestDataDependency.<Integer>perItem();
+
+        var first = dependency.resolve(creations::incrementAndGet);
+        var second = dependency.resolve(creations::incrementAndGet);
+
+        assertThat(first).isEqualTo(1);
+        assertThat(second).isEqualTo(2);
+        assertThat(creations).hasValue(2);
+        assertThat(dependency.isSet()).isFalse();
+    }
+
+    @Test
+    void set_pinsTheValueAndNeverCreates() {
+        var creations = new AtomicInteger();
+        var dependency = TestDataDependency.<Integer>perItem();
+
+        dependency.set(42);
+
+        assertThat(dependency.isSet()).isTrue();
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(42);
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(42);
+        assertThat(creations).hasValue(0);
+    }
+
+    @Test
+    void share_createsOnceAndReuses() {
+        var creations = new AtomicInteger();
+        var dependency = TestDataDependency.<Integer>perItem();
+
+        dependency.share();
+
+        assertThat(dependency.isSet()).isFalse();
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(1);
+        assertThat(dependency.isSet()).isTrue();
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(1);
+        assertThat(creations).hasValue(1);
+    }
+
+    @Test
+    void shared_startsInSharedMode() {
+        var creations = new AtomicInteger();
+        var dependency = TestDataDependency.<Integer>shared();
+
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(1);
+        assertThat(dependency.resolve(creations::incrementAndGet)).isEqualTo(1);
+        assertThat(creations).hasValue(1);
+    }
+
+    @Test
+    void shared_resolvesExactlyOnceUnderConcurrency() throws InterruptedException, ExecutionException {
+        var creations = new AtomicInteger();
+        var dependency = TestDataDependency.<Integer>shared();
+
+        var results = new HashSet<Integer>();
+        try (var executor = Executors.newFixedThreadPool(8)) {
+            var futures = new ArrayList<Future<Integer>>();
+            for (var i = 0; i < 8; i++) {
+                futures.add(executor.submit(() -> dependency.resolve(creations::incrementAndGet)));
+            }
+            for (var future : futures) {
+                results.add(future.get());
+            }
+        }
+
+        assertThat(creations).hasValue(1);
+        assertThat(results).containsExactly(1);
+    }
+}