@eventmodelers/cli 1.0.44 → 1.0.46

package/stacks/umadb/templates/root/pom.xml

@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>io.umadb.quickstart</groupId>
+    <artifactId>quickstart</artifactId>
+    <name>UmaDB Quickstart</name>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <properties>
+        <java.version>21</java.version>
+        <maven.compiler.release>21</maven.compiler.release>
+        <umadb-client.version>0.7</umadb-client.version>
+        <spring-boot.version>3.4.1</spring-boot.version>
+        <testcontainers.version>1.20.4</testcontainers.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <!-- Plain Spring MVC, not WebFlux: UmaDbClient's core API is blocking (returns Iterator,
+             not a Publisher), so a reactive web layer would only hide the blocking calls behind
+             a Mono, not remove them. Virtual threads (see application.properties) is this
+             project's answer to "many concurrent blocking gRPC calls" instead. -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- Read model persistence: Spring Data JPA + PostgreSQL, default for all projections -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <!-- UmaDB Java client (io.github.domenicdev is the published groupId; the classes
+             themselves live under the io.umadb.client package - see UmaDbConfig.java) -->
+        <dependency>
+            <groupId>io.github.domenicdev</groupId>
+            <artifactId>umadb-java-client</artifactId>
+            <version>${umadb-client.version}</version>
+        </dependency>
+
+        <!-- JSON codec for event/command payloads -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+
+        <!-- Auto-starts docker-compose.yml services (umadb, postgres) on app run -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-docker-compose</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Testing -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- @DataJpaTest's embedded database for fast, container-free projector tests -->
+        <dependency>
+            <groupId>com.h2database</groupId>
+            <artifactId>h2</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.awaitility</groupId>
+            <artifactId>awaitility</artifactId>
+            <version>4.2.2</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <release>${maven.compiler.release}</release>
+                    <parameters>true</parameters>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <!-- Mockito's inline mock maker (Byte Buddy) needs this on a JDK newer than
+                         its officially-supported range; harmless on older JDKs too. -->
+                    <argLine>-Dnet.bytebuddy.experimental=true</argLine>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring-boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+            <dependency>
+                <groupId>org.testcontainers</groupId>
+                <artifactId>testcontainers-bom</artifactId>
+                <version>${testcontainers.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+</project>

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/QuickstartApplication.java

@@ -0,0 +1,12 @@
+package io.umadb.quickstart;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class QuickstartApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(QuickstartApplication.class, args);
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/config/UmaDbConfig.java

@@ -0,0 +1,39 @@
+package io.umadb.quickstart.config;
+
+import io.umadb.client.UmaDbClient;
+import jakarta.annotation.PreDestroy;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Wires the shared {@link UmaDbClient} used by every command handler's read/append calls.
+ * UmaDB has no Spring Boot starter of its own (unlike Axon Framework) - the client is a
+ * plain library, so this project connects and shuts it down by hand, the same way the Axon
+ * quickstart wires its {@code TokenStore} bean manually.
+ * <p>
+ * {@link io.umadb.quickstart.eventstore.EventDispatcher} does NOT use this bean - it opens
+ * its own separate connection for the long-lived subscription. See that class's Javadoc.
+ */
+@Configuration
+public class UmaDbConfig {
+
+    private UmaDbClient client;
+
+    @Bean
+    public UmaDbClient umaDbClient(
+            @Value("${umadb.host}") String host,
+            @Value("${umadb.port}") int port
+    ) {
+        client = UmaDbClient.builder().withHost(host).withPort(port).build();
+        client.connect();
+        return client;
+    }
+
+    @PreDestroy
+    void shutdown() {
+        if (client != null) {
+            client.shutdown();
+        }
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/eventstore/DecisionModelLoader.java

@@ -0,0 +1,76 @@
+package io.umadb.quickstart.eventstore;
+
+import io.umadb.client.*;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+import java.util.function.BiConsumer;
+import java.util.function.Supplier;
+
+/**
+ * Shared read-decide-append loop every write slice's command handler uses - this project's
+ * hand-rolled equivalent of what an event-sourcing framework's aggregate repository would
+ * normally do, since the raw UmaDB client has no such layer of its own.
+ * <p>
+ * A command handler: (1) builds a {@link Query} scoped to the command's id tag(s) - see
+ * each slice's own {@code Decision.relevantEvents(...)} - (2) calls {@link #load} to replay
+ * matching prior events into a fresh decision-model instance, (3) checks the decision's
+ * flags/fields and throws if a business rule is violated, (4) calls {@link #append} with the
+ * SAME query and the position {@link #load} observed, so a conflicting event appended
+ * concurrently (by another instance of this same command, racing) fails the append instead
+ * of silently corrupting the decision - UmaDB's {@code AppendCondition.failIfExistsAfter}
+ * is what makes this a real consistency boundary, not just a convention.
+ */
+@Component
+public class DecisionModelLoader {
+
+    private final UmaDbClient client;
+
+    public DecisionModelLoader(UmaDbClient client) {
+        this.client = client;
+    }
+
+    /** The decision instance folded from prior matching events, plus the position observed while reading it. */
+    public record Loaded<D>(D decision, long lastPosition) {
+    }
+
+    /**
+     * Reads every event matching {@code query}, applying each to a fresh decision instance in
+     * store order. {@code apply} receives the raw {@link Event} - most decisions only need to
+     * know a matching event of a given {@code type()} existed (a boolean flag); only decode the
+     * payload via {@link EventCodec#fromEvent} when a scenario actually needs a field's value.
+     */
+    public <D> Loaded<D> load(Query query, Supplier<D> newDecision, BiConsumer<D, Event> apply) {
+        long lastPosition = client.getHeadPosition();
+        D decision = newDecision.get();
+        var batches = client.handle(ReadRequest.of(query));
+        while (batches.hasNext()) {
+            for (SequencedEvent sequencedEvent : batches.next().events()) {
+                apply.accept(decision, sequencedEvent.event());
+            }
+        }
+        return new Loaded<>(decision, lastPosition);
+    }
+
+    /**
+     * Appends the given domain event, guarded by an {@code AppendCondition} that fails if any
+     * event matching {@code consistencyBoundary} was appended after {@code lastPosition} - i.e.
+     * since this command's {@link #load} call read the state it decided against.
+     *
+     * @param consistencyBoundary same query {@link #load} used to read the decision this append follows from
+     * @param lastPosition        the position {@link #load} returned alongside that decision
+     * @throws OptimisticConcurrencyException if a conflicting event was appended concurrently
+     */
+    public void append(Object domainEvent, String type, List<String> tags, Query consistencyBoundary, long lastPosition) {
+        Event event = EventCodec.toEvent(domainEvent, type, tags);
+        try {
+            client.handle(new AppendRequest(
+                    List.of(event),
+                    AppendCondition.failIfExistsAfter(consistencyBoundary, lastPosition)
+            ));
+        } catch (UmaDbException.IntegrityException e) {
+            throw new OptimisticConcurrencyException(
+                    "Conflicting event(s) matching the consistency boundary were appended concurrently for event type " + type, e);
+        }
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/eventstore/EventCodec.java

@@ -0,0 +1,40 @@
+package io.umadb.quickstart.eventstore;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.umadb.client.Event;
+
+import java.util.List;
+
+/**
+ * Serializes domain event/command records to and from the opaque {@code byte[]} payload
+ * an UmaDB {@link Event} carries. UmaDB itself has no notion of a payload schema - this
+ * codec is this project's own convention (plain JSON via Jackson), not part of the UmaDB
+ * client API.
+ */
+public final class EventCodec {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private EventCodec() {
+    }
+
+    /** Serializes a domain event record into a new UmaDB {@link Event} with a generated id. */
+    public static Event toEvent(Object domainEvent, String type, List<String> tags) {
+        try {
+            byte[] data = MAPPER.writeValueAsBytes(domainEvent);
+            return Event.of(type, tags, data);
+        } catch (JsonProcessingException e) {
+            throw new IllegalStateException("Failed to serialize event of type " + type, e);
+        }
+    }
+
+    /** Deserializes an UmaDB {@link Event}'s payload back into the given domain event record type. */
+    public static <T> T fromEvent(Event event, Class<T> type) {
+        try {
+            return MAPPER.readValue(event.data(), type);
+        } catch (Exception e) {
+            throw new IllegalStateException("Failed to deserialize event of type " + event.type(), e);
+        }
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/eventstore/EventDispatcher.java

@@ -0,0 +1,100 @@
+package io.umadb.quickstart.eventstore;
+
+import io.umadb.client.SubscribeRequest;
+import io.umadb.client.UmaDbClient;
+import jakarta.annotation.PreDestroy;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+/**
+ * Fans out every event UmaDB has ever recorded (and every one appended from now on) to every
+ * {@link SliceEventListener} bean in the application - read-model projectors and automation
+ * processors alike. UmaDB has no built-in event-processor/subscription-group concept the way
+ * a framework like Axon does; this class is this project's one shared implementation of that
+ * plumbing, so no individual slice re-implements subscribe-and-fan-out itself.
+ * <p>
+ * Uses its own dedicated {@link UmaDbClient} connection (built directly from
+ * {@code umadb.host}/{@code umadb.port}, not the shared command-handling bean from
+ * {@link io.umadb.quickstart.config.UmaDbConfig}) because {@link UmaDbClient#subscribe} never
+ * returns until {@link UmaDbClient#shutdown()} is called - sharing a client would mean
+ * shutting down the dispatcher also kills every command handler's connection, and vice versa.
+ * <p>
+ * <b>Quickstart-level checkpointing only:</b> resubscribes from the very beginning of the
+ * stream on every application start (not from a persisted position). Every listener must
+ * therefore be idempotent under full replay - {@code AllCustomersProjector}'s JPA
+ * {@code save(...)} is (upsert by primary key), and {@code AutoSubscribeToDefaultCourseProcessor}
+ * relies on {@code SubscribeToCourseCommandHandler}'s own decision model to no-op a repeat
+ * dispatch. A production project should persist {@code getHeadPosition()} (or a per-listener
+ * cursor) and resume from there instead of always starting at 0 - UmaDB's {@code TrackingInfo}
+ * is the right tool for that (see {@code build-automation}'s translation-slice guidance for a
+ * worked example), but only fits naturally where the listener itself also appends an event;
+ * a pure projection has nothing to attach it to.
+ */
+@Component
+public class EventDispatcher {
+
+    private static final Logger log = LoggerFactory.getLogger(EventDispatcher.class);
+
+    private final String host;
+    private final int port;
+    private final List<SliceEventListener> listeners;
+
+    private volatile UmaDbClient subscriptionClient;
+    private volatile boolean shuttingDown;
+
+    public EventDispatcher(
+            @Value("${umadb.host}") String host,
+            @Value("${umadb.port}") int port,
+            List<SliceEventListener> listeners
+    ) {
+        this.host = host;
+        this.port = port;
+        this.listeners = List.copyOf(listeners);
+    }
+
+    @EventListener(ApplicationReadyEvent.class)
+    public void start() {
+        subscriptionClient = UmaDbClient.builder().withHost(host).withPort(port).build();
+        subscriptionClient.connect();
+        Thread.ofVirtual().name("umadb-event-dispatcher").start(this::runLoop);
+    }
+
+    private void runLoop() {
+        try {
+            var subscription = subscriptionClient.subscribe(SubscribeRequest.all());
+            while (subscription.hasNext()) {
+                for (var sequencedEvent : subscription.next().events()) {
+                    var event = sequencedEvent.event();
+                    for (SliceEventListener listener : listeners) {
+                        if (listener.supports(event.type())) {
+                            try {
+                                listener.onEvent(event);
+                            } catch (Exception e) {
+                                log.error("Listener {} failed handling event type {} at position {}",
+                                        listener.getClass().getSimpleName(), event.type(), sequencedEvent.position(), e);
+                            }
+                        }
+                    }
+                }
+            }
+        } catch (Exception e) {
+            if (!shuttingDown) {
+                log.error("Event dispatcher subscription terminated unexpectedly", e);
+            }
+        }
+    }
+
+    @PreDestroy
+    void shutdown() {
+        shuttingDown = true;
+        if (subscriptionClient != null) {
+            subscriptionClient.shutdown();
+        }
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/eventstore/OptimisticConcurrencyException.java

@@ -0,0 +1,14 @@
+package io.umadb.quickstart.eventstore;
+
+/**
+ * Thrown when a {@link DecisionModelLoader#append} call is rejected because an event
+ * matching the decision's own query was appended by someone else between the decision's
+ * read and its append - i.e. UmaDB's {@code AppendCondition} failed
+ * ({@code UmaDbException.IntegrityException}). Callers may retry the whole command from
+ * scratch (re-read, re-decide, re-append) or surface this as a conflict to the caller.
+ */
+public class OptimisticConcurrencyException extends RuntimeException {
+    public OptimisticConcurrencyException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

package/stacks/umadb/templates/root/src/main/java/io/umadb/quickstart/eventstore/SliceEventListener.java

@@ -0,0 +1,23 @@
+package io.umadb.quickstart.eventstore;
+
+import io.umadb.client.Event;
+
+/**
+ * Implemented by every read-model projector and automation processor that reacts to events
+ * off the live {@link EventDispatcher} subscription - this project's equivalent of an
+ * {@code @EventHandler}, since UmaDB has no annotation-driven dispatch of its own.
+ * Implementations decode the payload themselves (via {@link EventCodec#fromEvent}) once
+ * {@link #supports} confirms the type.
+ * <p>
+ * Named {@code Slice}EventListener, not {@code EventListener} - Spring's own
+ * {@code org.springframework.context.event.EventListener} annotation has that exact simple
+ * name, and {@link EventDispatcher} needs both in the same file.
+ */
+public interface SliceEventListener {
+
+    /** Whether this listener reacts to events of the given UmaDB {@code Event.type()}. */
+    boolean supports(String eventType);
+
+    /** Handle one matching event. Called on the dispatcher's subscription thread - keep it fast and idempotent. */
+    void onEvent(Event event);
+}

package/stacks/umadb/templates/root/src/main/resources/application.properties

@@ -0,0 +1,17 @@
+spring.application.name=UmaDB Quickstart
+spring.threads.virtual.enabled=true
+
+umadb.host=localhost
+umadb.port=50051
+
+spring.datasource.url=jdbc:postgresql://localhost:5432/quickstart
+spring.datasource.username=quickstart
+spring.datasource.password=quickstart
+spring.jpa.hibernate.ddl-auto=update
+
+spring.docker.compose.enabled=true
+spring.docker.compose.file=docker-compose.yml
+
+# Each write/automation slice's build skill adds one line here of the form
+# slices.{context}.write.{slicename}.enabled=true (or slices.{context}.automation.{slicename}.enabled=true)
+# - see build-kit/CLAUDE.md's feature-flag convention.

package/stacks/umadb/templates/root/src/test/java/io/umadb/quickstart/testsupport/InMemoryUmaDbClient.java

@@ -0,0 +1,135 @@
+package io.umadb.quickstart.testsupport;
+
+import io.umadb.client.*;
+
+import java.util.*;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * Fast, in-process fake of {@link UmaDbClient} for command-handler unit tests - this project's
+ * hand-rolled stand-in for what {@code AxonTestFixture} gives Axon Framework projects, since
+ * UmaDB ships no test-fixture library of its own (only a Testcontainers-based integration test
+ * setup - see {@code UmaDbContainerTest} for that style instead).
+ * <p>
+ * Reimplements the real server's documented matching rules ({@link Query}/{@link QueryItem}) and
+ * conflict/idempotency semantics ({@link AppendCondition}, id-based dedup) closely enough for
+ * command-handler tests, but is NOT a certified reproduction of the real server - anything
+ * subtle should still be verified against a real instance via Testcontainers
+ * ({@code UmaDbContainerTest}). {@link #subscribe} is intentionally unsupported: no test in this
+ * project needs it, since projectors are tested via a direct {@code on(event)} call instead (see
+ * build-state-view) and the one thing that genuinely needs a live subscription
+ * ({@link io.umadb.quickstart.eventstore.EventDispatcher}) is covered by the Testcontainers test.
+ */
+public class InMemoryUmaDbClient implements UmaDbClient {
+
+    private final List<SequencedEvent> store = new CopyOnWriteArrayList<>();
+
+    @Override
+    public void connect() {
+        // no-op: nothing to connect to
+    }
+
+    @Override
+    public synchronized AppendResponse handle(AppendRequest appendRequest) {
+        // Idempotency: if every event in this request already exists by id, no-op and return
+        // the position of the last of those - mirrors the real server's documented behaviour
+        // (verified against UmaDbClientTest#testIdempotentAppendReturnsSamePosition upstream).
+        boolean allAlreadyExist = appendRequest.events().stream().allMatch(this::existsById);
+        if (allAlreadyExist && !appendRequest.events().isEmpty()) {
+            long position = appendRequest.events().stream()
+                    .mapToLong(e -> positionOf(e).orElseThrow())
+                    .max().orElseThrow();
+            return new AppendResponse(position);
+        }
+
+        if (appendRequest.condition() != null) {
+            AppendCondition condition = appendRequest.condition();
+            long after = condition.after() == null ? 0L : condition.after();
+            boolean conflict = store.stream()
+                    .anyMatch(se -> se.position() > after && matches(condition.failIfEventsMatch(), se.event()));
+            if (conflict) {
+                throw new UmaDbException.IntegrityException(
+                        "Event(s) matching the append condition already exist after position " + after);
+            }
+        }
+
+        long position = store.size();
+        for (Event event : appendRequest.events()) {
+            position++;
+            store.add(new SequencedEvent(position, event, appendRequest.trackingInfo()));
+        }
+        return new AppendResponse(position);
+    }
+
+    @Override
+    public synchronized Iterator<ReadResponse> handle(ReadRequest readRequest) {
+        long start = readRequest.start() == null ? 0L : readRequest.start();
+        boolean backwards = readRequest.backwards() != null && readRequest.backwards();
+
+        List<SequencedEvent> matched = store.stream()
+                .filter(se -> se.position() > start)
+                .filter(se -> matches(readRequest.query(), se.event()))
+                .sorted(backwards
+                        ? Comparator.comparingLong(SequencedEvent::position).reversed()
+                        : Comparator.comparingLong(SequencedEvent::position))
+                .toList();
+
+        if (readRequest.limit() != null && matched.size() > readRequest.limit()) {
+            matched = matched.subList(0, readRequest.limit());
+        }
+
+        long head = store.isEmpty() ? 0L : store.get(store.size() - 1).position();
+        return List.of(new ReadResponse(matched, head)).iterator();
+    }
+
+    @Override
+    public Iterator<SubscribeResponse> subscribe(SubscribeRequest subscribeRequest) {
+        throw new UnsupportedOperationException(
+                "InMemoryUmaDbClient does not support subscribe() - test projectors via a direct "
+                        + "on(event) call instead, and test EventDispatcher itself against a real "
+                        + "instance via Testcontainers (see UmaDbContainerTest).");
+    }
+
+    @Override
+    public synchronized Optional<Long> getTrackingInfo(String source) {
+        return store.stream()
+                .filter(se -> se.trackingInfo() != null && se.trackingInfo().source().equals(source))
+                .max(Comparator.comparingLong(SequencedEvent::position))
+                .map(se -> se.trackingInfo().position());
+    }
+
+    @Override
+    public synchronized long getHeadPosition() {
+        return store.isEmpty() ? 0L : store.get(store.size() - 1).position();
+    }
+
+    @Override
+    public void shutdown() {
+        // no-op
+    }
+
+    private boolean existsById(Event event) {
+        return store.stream().anyMatch(se -> se.event().id().equals(event.id()));
+    }
+
+    private Optional<Long> positionOf(Event event) {
+        return store.stream()
+                .filter(se -> se.event().id().equals(event.id()))
+                .map(SequencedEvent::position)
+                .max(Long::compareTo);
+    }
+
+    /** {@code Query}/{@code QueryItem} matching rules, replicated from their own javadoc. */
+    private static boolean matches(Query query, Event event) {
+        if (query == null || query.items().isEmpty()) {
+            return true;
+        }
+        return query.items().stream().anyMatch(item -> matches(item, event));
+    }
+
+    private static boolean matches(QueryItem item, Event event) {
+        boolean typeMatches = item.types().isEmpty() || item.types().contains(event.type());
+        boolean tagsMatch = item.tags().isEmpty() || event.tags().containsAll(item.tags());
+        return typeMatches && tagsMatch;
+    }
+}

package/stacks/umadb/templates/root/src/test/resources/application.properties

@@ -0,0 +1,8 @@
+spring.datasource.url=jdbc:postgresql://localhost:5432/quickstart
+spring.datasource.username=quickstart
+spring.datasource.password=quickstart
+
+# Each write/automation slice's build skill adds one line here of the form
+# slices.{context}.write.{slicename}.enabled=false (or slices.{context}.automation.{slicename}.enabled=false)
+# so fast unit tests never boot a real UmaDbClient/EventDispatcher. A Testcontainers-based
+# end-to-end test (see build-state-view's reference) overrides these back to true for itself.