query, ExecutionContext context) {
})
.then(Mono.defer(() -> {
// Check if caching is enabled and query is cacheable
- if (cacheAdapter != null && query.isCacheable() && query.getCacheKey() != null) {
+ if (cacheAdapter != null && query.isCacheable() && handler.supportsCaching()) {
String cacheKey = query.getCacheKey();
-
- return cacheAdapter.get(cacheKey, query.getResultType())
- .doOnNext(cachedResult -> log.debug("CQRS Query Cache Hit - Type: {}, ID: {}, CacheKey: {}",
- query.getClass().getSimpleName(), query.getQueryId(), cacheKey))
- .doOnSuccess(result -> {
- if (result != null) {
- log.info("CQRS Query Processing Completed from Cache - Type: {}, ID: {}, Result: {}",
- query.getClass().getSimpleName(), query.getQueryId(),
- result != null ? "Success" : "Null");
- }
- })
- .switchIfEmpty(Mono.defer(() -> {
- // Cache miss - execute handler and cache result
- log.debug("CQRS Query Cache Miss - Type: {}, ID: {}, CacheKey: {}",
- query.getClass().getSimpleName(), query.getQueryId(), cacheKey);
- return executeWithMetrics(handler, query, context)
- .flatMap(result -> {
- if (result != null) {
- return cacheAdapter.put(cacheKey, result)
- .thenReturn(result)
- .doOnSuccess(r -> log.debug("CQRS Query Result Cached - Type: {}, ID: {}, CacheKey: {}",
- query.getClass().getSimpleName(), query.getQueryId(), cacheKey));
- }
- return Mono.just(result);
- })
- .doOnSuccess(result -> log.info("CQRS Query Processing Completed with Context - Type: {}, ID: {}, Result: {}",
- query.getClass().getSimpleName(), query.getQueryId(),
- result != null ? "Success" : "Null"))
- .doOnError(error -> log.error("CQRS Query Processing Failed with Context - Type: {}, ID: {}, Error: {}, Cause: {}",
+ if (cacheKey != null) {
+ return cacheAdapter.get(cacheKey, query.getResultType())
+ .doOnNext(cachedResult -> log.debug("CQRS Query Cache Hit - Type: {}, ID: {}, CacheKey: {}",
+ query.getClass().getSimpleName(), query.getQueryId(), cacheKey))
+ .doOnSuccess(result -> {
+ if (result != null) {
+ log.info("CQRS Query Processing Completed from Cache - Type: {}, ID: {}, Result: {}",
query.getClass().getSimpleName(), query.getQueryId(),
- error.getClass().getSimpleName(), error.getMessage(), error));
- }))
- .doFinally(signalType -> correlationContext.clear());
+ result != null ? "Success" : "Null");
+ }
+ })
+ .switchIfEmpty(Mono.defer(() -> {
+ // Cache miss - execute handler and cache result
+ log.debug("CQRS Query Cache Miss - Type: {}, ID: {}, CacheKey: {}",
+ query.getClass().getSimpleName(), query.getQueryId(), cacheKey);
+ return executeWithMetrics(handler, query, context)
+ .flatMap(result -> {
+ if (result != null) {
+ return cacheAdapter.put(cacheKey, result)
+ .thenReturn(result)
+ .doOnSuccess(r -> log.debug("CQRS Query Result Cached - Type: {}, ID: {}, CacheKey: {}",
+ query.getClass().getSimpleName(), query.getQueryId(), cacheKey));
+ }
+ return Mono.just(result);
+ })
+ .doOnSuccess(result -> log.info("CQRS Query Processing Completed with Context - Type: {}, ID: {}, Result: {}",
+ query.getClass().getSimpleName(), query.getQueryId(),
+ result != null ? "Success" : "Null"))
+ .doOnError(error -> log.error("CQRS Query Processing Failed with Context - Type: {}, ID: {}, Error: {}, Cause: {}",
+ query.getClass().getSimpleName(), query.getQueryId(),
+ error.getClass().getSimpleName(), error.getMessage(), error));
+ }))
+ .doFinally(signalType -> correlationContext.clear());
+ }
}
// Execute without caching
@@ -424,4 +425,4 @@ public QueryProcessingException(String message, Throwable cause) {
super(message, cause);
}
}
-}
\ No newline at end of file
+}
diff --git a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/Query.java b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/Query.java
index ed9d1a8bf..48dd0dbfb 100644
--- a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/Query.java
+++ b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/Query.java
@@ -108,33 +108,22 @@ default boolean isCacheable() {
}
/**
- * Cache key for this query if caching is enabled.
- * Default implementation uses query class name and metadata hash.
- * The cache key will be automatically prefixed with ":cqrs:" by the QueryCacheAdapter.
- * Combined with fireflyframework-cache's "firefly:cache:{cacheName}:" prefix, final keys are:
- *
- * - Caffeine: "firefly:cache:default::cqrs:QueryName"
- * - Redis: "firefly:cache:default::cqrs:QueryName"
- *
+ * Cache key for this query, or {@code null} to execute without caching.
*
- * The double colon (::) between the cache name and the CQRS namespace provides
- * clear visual separation between the cache infrastructure prefix and the application-level namespace.
+ *
Caching requires an explicit key. A class name or metadata hash cannot
+ * identify all business inputs or the authority under which a result is read.
+ * Override this method only when the key includes every result-affecting input
+ * and the relevant trusted tenant, subject, and policy scope. Do not put raw
+ * personal data or credentials in a key. Handlers requiring current state
+ * should disable caching through {@code @QueryHandlerComponent(cacheable = false)}.
*
- * @return cache key (without prefix), or null to disable caching for this instance
+ *
The cache adapter adds its CQRS namespace to an explicitly supplied key.
+ * Existing class-name and metadata-only entries are not read by this default.
+ *
+ * @return an explicitly scoped cache key, or null by default
*/
default String getCacheKey() {
- if (!isCacheable()) {
- return null;
- }
-
- String baseKey = this.getClass().getSimpleName();
- Map metadata = getMetadata();
-
- if (metadata != null && !metadata.isEmpty()) {
- return baseKey + ":" + metadata.hashCode();
- }
-
- return baseKey;
+ return null;
}
/**
diff --git a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/QueryHandler.java b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/QueryHandler.java
index 757a81026..f2bfba4d7 100644
--- a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/QueryHandler.java
+++ b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/query/QueryHandler.java
@@ -30,7 +30,7 @@
* This is the only way to create query handlers. It provides:
*
* - Zero Boilerplate: Automatic type detection from generics
- * - Smart Caching: Built-in caching with configurable TTL and automatic key generation
+ * - Query Caching: Optional result caching with explicitly scoped query keys
* - Performance Monitoring: Automatic timing and success/failure tracking
* - Extensibility: Pre/post processing hooks for custom logic
* - Clean API: Just implement doHandle() - everything else is automatic
diff --git a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/util/GenericTypeResolver.java b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/util/GenericTypeResolver.java
index 9588170fd..7363e8742 100644
--- a/modules/cqrs/src/main/java/org/fireflyframework/cqrs/util/GenericTypeResolver.java
+++ b/modules/cqrs/src/main/java/org/fireflyframework/cqrs/util/GenericTypeResolver.java
@@ -22,6 +22,10 @@
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.lang.reflect.TypeVariable;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
/**
* Utility class for resolving generic type parameters at runtime.
@@ -77,31 +81,10 @@ public static Class resolveGenericType(Class implementationClass,
log.debug("Resolving generic type for class: {} extending/implementing: {} at index: {}",
implementationClass.getName(), targetClass.getName(), typeParameterIndex);
- // Walk up the class hierarchy
- Class currentClass = implementationClass;
- while (currentClass != null && currentClass != Object.class) {
-
- // Check direct interfaces
- Type[] interfaces = currentClass.getGenericInterfaces();
- for (Type interfaceType : interfaces) {
- Class resolvedType = extractTypeFromInterface(interfaceType, targetClass, typeParameterIndex);
- if (resolvedType != null) {
- log.debug("Resolved generic type: {} for class: {}", resolvedType.getName(), implementationClass.getName());
- return resolvedType;
- }
- }
-
- // Check superclass
- Type superclass = currentClass.getGenericSuperclass();
- if (superclass instanceof ParameterizedType) {
- Class resolvedType = extractTypeFromSuperclass(superclass, targetClass, typeParameterIndex, currentClass);
- if (resolvedType != null) {
- log.debug("Resolved generic type from superclass: {} for class: {}", resolvedType.getName(), implementationClass.getName());
- return resolvedType;
- }
- }
-
- currentClass = currentClass.getSuperclass();
+ Class resolvedType = resolveFromHierarchy(implementationClass, targetClass, typeParameterIndex, Map.of());
+ if (resolvedType != null) {
+ log.debug("Resolved generic type: {} for class: {}", resolvedType.getName(), implementationClass.getName());
+ return resolvedType;
}
log.error("Could not resolve generic type for class: {} extending/implementing: {} at index: {}\n{}",
@@ -110,77 +93,61 @@ public static Class resolveGenericType(Class implementationClass,
return null;
}
- /**
- * Extracts type information from a parameterized interface.
- */
@SuppressWarnings("unchecked")
- private static Class extractTypeFromInterface(Type interfaceType,
- Class targetClass,
- int typeParameterIndex) {
- if (!(interfaceType instanceof ParameterizedType)) {
+ private static Class resolveFromHierarchy(Type type, Class targetClass,
+ int typeParameterIndex,
+ Map, Type> inheritedBindings) {
+ Class rawClass;
+ Map, Type> bindings = new HashMap<>(inheritedBindings);
+ if (type instanceof ParameterizedType parameterizedType) {
+ rawClass = (Class) parameterizedType.getRawType();
+ TypeVariable[] parameters = rawClass.getTypeParameters();
+ Type[] arguments = parameterizedType.getActualTypeArguments();
+ for (int i = 0; i < parameters.length; i++) {
+ bindings.put(parameters[i], resolveBinding(arguments[i], inheritedBindings));
+ }
+ } else if (type instanceof Class typeClass) {
+ rawClass = typeClass;
+ } else {
return null;
}
- ParameterizedType parameterizedType = (ParameterizedType) interfaceType;
- Type rawType = parameterizedType.getRawType();
-
- // Check if this is the target interface
- if (rawType.equals(targetClass)) {
- Type[] typeArguments = parameterizedType.getActualTypeArguments();
-
- if (typeParameterIndex >= typeArguments.length) {
- log.warn("Type parameter index {} is out of bounds for interface {} with {} type arguments",
- typeParameterIndex, targetClass.getName(), typeArguments.length);
+ if (rawClass == targetClass) {
+ TypeVariable[] parameters = rawClass.getTypeParameters();
+ if (typeParameterIndex >= parameters.length) {
return null;
}
-
- Type typeArgument = typeArguments[typeParameterIndex];
- if (typeArgument instanceof Class) {
- return (Class) typeArgument;
- } else if (typeArgument instanceof ParameterizedType) {
- Type rawTypeArg = ((ParameterizedType) typeArgument).getRawType();
- if (rawTypeArg instanceof Class) {
- return (Class) rawTypeArg;
- }
+ Type argument = resolveBinding(parameters[typeParameterIndex], bindings);
+ if (argument instanceof Class argumentClass) {
+ return (Class) argumentClass;
+ }
+ if (argument instanceof ParameterizedType parameterizedArgument) {
+ return (Class) parameterizedArgument.getRawType();
}
- }
-
- return null;
- }
-
- /**
- * Extracts type information from a parameterized superclass.
- */
- @SuppressWarnings("unchecked")
- private static Class extractTypeFromSuperclass(Type superclass,
- Class targetClass,
- int typeParameterIndex,
- Class currentClass) {
- if (!(superclass instanceof ParameterizedType)) {
return null;
}
- ParameterizedType parameterizedSuperclass = (ParameterizedType) superclass;
- Class superclassRaw = (Class) parameterizedSuperclass.getRawType();
-
- // Check if this superclass IS the target class (for abstract classes like CommandHandler)
- if (superclassRaw.equals(targetClass)) {
- Type[] typeArguments = parameterizedSuperclass.getActualTypeArguments();
- if (typeArguments.length > typeParameterIndex) {
- Type typeArg = typeArguments[typeParameterIndex];
- if (typeArg instanceof Class) {
- return (Class) typeArg;
- } else if (typeArg instanceof ParameterizedType) {
- Type rawTypeArg = ((ParameterizedType) typeArg).getRawType();
- if (rawTypeArg instanceof Class) {
- return (Class) rawTypeArg;
- }
- }
+ for (Type interfaceType : rawClass.getGenericInterfaces()) {
+ Class resolvedType = resolveFromHierarchy(interfaceType, targetClass, typeParameterIndex, bindings);
+ if (resolvedType != null) {
+ return resolvedType;
}
}
+ Type superclass = rawClass.getGenericSuperclass();
+ return superclass != null ? resolveFromHierarchy(superclass, targetClass, typeParameterIndex, bindings) : null;
+ }
- // Recursively check if the superclass implements the target interface (for interfaces)
- return resolveGenericType(superclassRaw, targetClass, typeParameterIndex);
+ private static Type resolveBinding(Type type, Map, Type> bindings) {
+ Set visited = new HashSet<>();
+ while (type instanceof TypeVariable && visited.add(type)) {
+ Type binding = bindings.get(type);
+ if (binding == null) {
+ break;
+ }
+ type = binding;
+ }
+ // Unbound variables stay unresolved rather than becoming their upper bounds.
+ return type;
}
/**
diff --git a/modules/cqrs/src/test/java/org/fireflyframework/cqrs/integration/QueryCacheIsolationTest.java b/modules/cqrs/src/test/java/org/fireflyframework/cqrs/integration/QueryCacheIsolationTest.java
new file mode 100644
index 000000000..f622ce9c8
--- /dev/null
+++ b/modules/cqrs/src/test/java/org/fireflyframework/cqrs/integration/QueryCacheIsolationTest.java
@@ -0,0 +1,123 @@
+package org.fireflyframework.cqrs.integration;
+
+import org.fireflyframework.cache.config.CacheAutoConfiguration;
+import org.fireflyframework.cqrs.annotations.QueryHandlerComponent;
+import org.fireflyframework.cqrs.cache.QueryCacheAdapter;
+import org.fireflyframework.cqrs.config.CqrsAutoConfiguration;
+import org.fireflyframework.cqrs.context.ExecutionContext;
+import org.fireflyframework.cqrs.query.DefaultQueryBus;
+import org.fireflyframework.cqrs.query.Query;
+import org.fireflyframework.cqrs.query.QueryHandler;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.test.context.TestPropertySource;
+import reactor.core.publisher.Mono;
+
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest(classes = {CacheAutoConfiguration.class, CqrsAutoConfiguration.class,
+ QueryCacheIsolationTest.TestConfig.class})
+@TestPropertySource(properties = {"firefly.cache.enabled=true", "firefly.cache.default-cache-type=CAFFEINE"})
+class QueryCacheIsolationTest {
+ @Configuration
+ static class TestConfig { }
+
+ @Autowired DefaultQueryBus bus;
+ @Autowired QueryCacheAdapter cache;
+ private UnkeyedHandler unkeyed;
+ private KeyedHandler keyed;
+ private FreshHandler fresh;
+
+ @BeforeEach
+ void reset() {
+ cache.clear().block();
+ unkeyed = new UnkeyedHandler();
+ keyed = new KeyedHandler();
+ fresh = new FreshHandler();
+ bus.registerHandler(unkeyed);
+ bus.registerHandler(keyed);
+ bus.registerHandler(fresh);
+ }
+
+ @Test
+ void defaultKeyDoesNotGuessTheCompleteQueryIdentity() {
+ assertThat(new Unkeyed("request-a").getCacheKey()).isNull();
+ Query metadataOnly = new Query<>() {
+ @Override public Map getMetadata() { return Map.of("page", 1); }
+ };
+ assertThat(metadataOnly.getCacheKey()).isNull();
+ }
+
+ @ParameterizedTest
+ @ValueSource(booleans = {false, true})
+ void differentInputsNeverShareAnImplicitClassKey(boolean contextual) {
+ assertThat(read(new Unkeyed("request-a"), contextual)).isEqualTo("request-a");
+ assertThat(read(new Unkeyed("request-b"), contextual)).isEqualTo("request-b");
+ assertThat(read(new Unkeyed("request-a"), contextual)).isEqualTo("request-a");
+ assertThat(unkeyed.calls).hasValue(3);
+ }
+
+ @ParameterizedTest
+ @ValueSource(booleans = {false, true})
+ void explicitlyScopedKeysStillCacheAndIsolateInputs(boolean contextual) {
+ assertThat(read(new Keyed("request-a"), contextual)).isEqualTo("request-a");
+ assertThat(read(new Keyed("request-b"), contextual)).isEqualTo("request-b");
+ assertThat(read(new Keyed("request-a"), contextual)).isEqualTo("request-a");
+ assertThat(keyed.calls).hasValue(2);
+ }
+
+ @ParameterizedTest
+ @ValueSource(booleans = {false, true})
+ void authoritativeHandlerDisablesBothCacheReadsAndWrites(boolean contextual) {
+ cache.put("fresh:request-a", "stale").block();
+ assertThat(read(new Fresh("request-a"), contextual)).isEqualTo("request-a:1");
+ assertThat(read(new Fresh("request-a"), contextual)).isEqualTo("request-a:2");
+ assertThat(cache.get("fresh:request-a", String.class).block()).isEqualTo("stale");
+ }
+
+ private String read(Query query, boolean contextual) {
+ return (contextual ? bus.query(query, ExecutionContext.builder().withTenantId("fixture-tenant").build())
+ : bus.query(query)).block();
+ }
+
+ record Unkeyed(String requestId) implements Query { }
+ record Keyed(String requestId) implements Query {
+ @Override public String getCacheKey() { return "fixture-tenant:keyed:" + requestId; }
+ @Override public Class getResultType() { return String.class; }
+ }
+ record Fresh(String requestId) implements Query {
+ @Override public String getCacheKey() { return "fresh:" + requestId; }
+ @Override public Class getResultType() { return String.class; }
+ }
+ @QueryHandlerComponent
+ static class UnkeyedHandler extends QueryHandler {
+ final AtomicInteger calls = new AtomicInteger();
+ @Override protected Mono doHandle(Unkeyed query) {
+ calls.incrementAndGet();
+ return Mono.just(query.requestId());
+ }
+ }
+ @QueryHandlerComponent
+ static class KeyedHandler extends QueryHandler {
+ final AtomicInteger calls = new AtomicInteger();
+ @Override protected Mono doHandle(Keyed query) {
+ calls.incrementAndGet();
+ return Mono.just(query.requestId());
+ }
+ }
+ @QueryHandlerComponent(cacheable = false)
+ static class FreshHandler extends QueryHandler {
+ @Override protected Mono doHandle(Fresh query) {
+ return Mono.just(query.requestId() + ":" + calls.incrementAndGet());
+ }
+ final AtomicInteger calls = new AtomicInteger();
+ }
+}
diff --git a/modules/cqrs/src/test/java/org/fireflyframework/cqrs/util/GenericTypeResolverTest.java b/modules/cqrs/src/test/java/org/fireflyframework/cqrs/util/GenericTypeResolverTest.java
new file mode 100644
index 000000000..c11d4febd
--- /dev/null
+++ b/modules/cqrs/src/test/java/org/fireflyframework/cqrs/util/GenericTypeResolverTest.java
@@ -0,0 +1,133 @@
+package org.fireflyframework.cqrs.util;
+
+import org.fireflyframework.cqrs.command.Command;
+import org.fireflyframework.cqrs.command.CommandHandler;
+import org.fireflyframework.cqrs.command.ContextAwareCommandHandler;
+import org.fireflyframework.cqrs.context.ExecutionContext;
+import org.fireflyframework.cqrs.query.ContextAwareQueryHandler;
+import org.fireflyframework.cqrs.query.Query;
+import org.fireflyframework.cqrs.query.QueryHandler;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class GenericTypeResolverTest {
+ @Test
+ void constructsContextAwareCommandHandlerWithConcreteRequestAndResultTypes() {
+ var handler = new ContextCommand();
+ assertThat(handler.getCommandType()).isEqualTo(TestCommand.class);
+ assertThat(handler.getResultType()).isEqualTo(String.class);
+ }
+
+ @Test
+ void constructsContextAwareQueryHandlerWithConcreteRequestAndResultTypes() {
+ var handler = new ContextQuery();
+ assertThat(handler.getQueryType()).isEqualTo(TestQuery.class);
+ assertThat(handler.getResultType()).isEqualTo(String.class);
+ }
+
+ @Test
+ void carriesReorderedCommandBindingsAcrossMultipleSuperclasses() {
+ var handler = new InheritedCommand();
+ assertThat(handler.getCommandType()).isEqualTo(TestCommand.class);
+ assertThat(handler.getResultType()).isEqualTo(String.class);
+ }
+
+ @Test
+ void carriesReorderedQueryBindingsAcrossMultipleSuperclasses() {
+ var handler = new InheritedQuery();
+ assertThat(handler.getQueryType()).isEqualTo(TestQuery.class);
+ assertThat(handler.getResultType()).isEqualTo(String.class);
+ }
+
+ @Test
+ void resolvesInheritedInterfaceBindingsWithoutAssumingParameterOrder() {
+ assertThat(GenericTypeResolver.resolveGenericType(InterfaceImplementation.class, Pair.class, 0)).isEqualTo(String.class);
+ assertThat(GenericTypeResolver.resolveGenericType(InterfaceImplementation.class, Pair.class, 1)).isEqualTo(Integer.class);
+ }
+
+ @Test
+ void retainsRawClassOfResolvedParameterizedArguments() {
+ assertThat(GenericTypeResolver.resolveGenericType(ListImplementation.class, Pair.class, 0)).isEqualTo(List.class);
+ assertThat(GenericTypeResolver.resolveGenericType(ListImplementation.class, Pair.class, 1)).isEqualTo(String.class);
+ }
+
+ @Test
+ void unresolvedCommandVariableDoesNotFallBackToItsCommandBound() {
+ assertThat(GenericTypeResolver.resolveGenericType(UnresolvedCommand.class, CommandHandler.class, 0)).isNull();
+ assertThatThrownBy(() -> GenericTypeResolver.resolveCommandType(UnresolvedCommand.class))
+ .isInstanceOf(GenericTypeResolver.TypeResolutionException.class);
+ }
+
+ @Test
+ void unresolvedQueryVariableDoesNotFallBackToItsQueryBound() {
+ assertThat(GenericTypeResolver.resolveQueryType(UnresolvedQuery.class)).isNull();
+ }
+
+ @Test
+ void rawContextAwareHandlersRemainUnresolved() {
+ assertThat(GenericTypeResolver.resolveGenericType(ContextAwareCommandHandler.class, CommandHandler.class, 0)).isNull();
+ assertThat(GenericTypeResolver.resolveGenericType(ContextAwareCommandHandler.class, CommandHandler.class, 1)).isNull();
+ assertThat(GenericTypeResolver.resolveQueryType(ContextAwareQueryHandler.class)).isNull();
+ assertThat(GenericTypeResolver.resolveQueryResultType(ContextAwareQueryHandler.class)).isNull();
+ }
+
+ @Test
+ void rawAndUnresolvedInterfacesRemainUnresolved() {
+ assertThat(GenericTypeResolver.resolveGenericType(RawImplementation.class, Pair.class, 0)).isNull();
+ assertThat(GenericTypeResolver.resolveGenericType(UnresolvedPair.class, Pair.class, 0)).isNull();
+ }
+
+ @Test
+ void explicitlyBoundObjectRemainsAValidResultType() {
+ assertThat(GenericTypeResolver.resolveGenericType(ObjectImplementation.class, Pair.class, 0)).isEqualTo(Object.class);
+ }
+
+ @Test
+ void unrelatedTargetAndOutOfRangeIndexRemainUnresolved() {
+ assertThat(GenericTypeResolver.resolveGenericType(String.class, Pair.class, 0)).isNull();
+ assertThat(GenericTypeResolver.resolveGenericType(InterfaceImplementation.class, Pair.class, 2)).isNull();
+ }
+
+ @Test
+ void rejectsNullInputsAndNegativeIndices() {
+ assertThatThrownBy(() -> GenericTypeResolver.resolveGenericType(null, Pair.class, 0)).isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> GenericTypeResolver.resolveGenericType(InterfaceImplementation.class, null, 0)).isInstanceOf(IllegalArgumentException.class);
+ assertThatThrownBy(() -> GenericTypeResolver.resolveGenericType(InterfaceImplementation.class, Pair.class, -1)).isInstanceOf(IllegalArgumentException.class);
+ }
+
+ record TestCommand() implements Command { }
+ record TestQuery() implements Query { }
+
+ static class ContextCommand extends ContextAwareCommandHandler {
+ @Override protected Mono doHandle(TestCommand command, ExecutionContext context) { return Mono.just("command"); }
+ }
+ static class ContextQuery extends ContextAwareQueryHandler {
+ @Override protected Mono doHandle(TestQuery query, ExecutionContext context) { return Mono.just("query"); }
+ }
+ abstract static class ReorderedCommand> extends ContextAwareCommandHandler { }
+ static class BoundCommand extends ReorderedCommand {
+ @Override protected Mono doHandle(TestCommand command, ExecutionContext context) { return Mono.just("command"); }
+ }
+ static class InheritedCommand extends BoundCommand { }
+ abstract static class ReorderedQuery> extends ContextAwareQueryHandler { }
+ static class BoundQuery extends ReorderedQuery {
+ @Override protected Mono doHandle(TestQuery query, ExecutionContext context) { return Mono.just("query"); }
+ }
+ static class InheritedQuery extends BoundQuery { }
+ abstract static class UnresolvedCommand> extends ContextAwareCommandHandler { }
+ abstract static class UnresolvedQuery> extends ContextAwareQueryHandler { }
+ interface Pair { }
+ interface ReorderedPair extends Pair { }
+ abstract static class PairBase implements ReorderedPair { }
+ static class InterfaceImplementation extends PairBase { }
+ static class ListImplementation extends PairBase, String> { }
+ static class ObjectImplementation extends PairBase { }
+ static class UnresolvedPair extends PairBase { }
+ @SuppressWarnings("rawtypes")
+ static class RawImplementation implements Pair { }
+}
diff --git a/modules/ecm-esignature-adobe-sign/README.md b/modules/ecm-esignature-adobe-sign/README.md
index bc6edef24..c46535f02 100644
--- a/modules/ecm-esignature-adobe-sign/README.md
+++ b/modules/ecm-esignature-adobe-sign/README.md
@@ -20,7 +20,7 @@ If onboarding includes a signed agreement, use the Adobe Sign adapter for the co
org.fireflyframework
fireflyframework-ecm-esignature-adobe-sign
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm-esignature-adobe-sign/pom.xml b/modules/ecm-esignature-adobe-sign/pom.xml
index 13c3ab453..637fa9847 100644
--- a/modules/ecm-esignature-adobe-sign/pom.xml
+++ b/modules/ecm-esignature-adobe-sign/pom.xml
@@ -7,13 +7,13 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
org.fireflyframework
fireflyframework-ecm-esignature-adobe-sign
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - ECM eSignature - Adobe Sign
diff --git a/modules/ecm-esignature-docusign/README.md b/modules/ecm-esignature-docusign/README.md
index 4abcf611c..1125de16b 100644
--- a/modules/ecm-esignature-docusign/README.md
+++ b/modules/ecm-esignature-docusign/README.md
@@ -20,7 +20,7 @@ If onboarding includes a signed agreement, use the DocuSign adapter for the conf
org.fireflyframework
fireflyframework-ecm-esignature-docusign
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm-esignature-docusign/pom.xml b/modules/ecm-esignature-docusign/pom.xml
index 7361cd589..9c658e0ca 100644
--- a/modules/ecm-esignature-docusign/pom.xml
+++ b/modules/ecm-esignature-docusign/pom.xml
@@ -7,13 +7,13 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
org.fireflyframework
fireflyframework-ecm-esignature-docusign
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - ECM eSignature - DocuSign
diff --git a/modules/ecm-esignature-logalty/README.md b/modules/ecm-esignature-logalty/README.md
index 736987434..7ae106c6e 100644
--- a/modules/ecm-esignature-logalty/README.md
+++ b/modules/ecm-esignature-logalty/README.md
@@ -20,7 +20,7 @@ If onboarding includes a signed agreement, use the Logalty adapter for the confi
org.fireflyframework
fireflyframework-ecm-esignature-logalty
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm-esignature-logalty/pom.xml b/modules/ecm-esignature-logalty/pom.xml
index bd3dda9b5..20ad06fca 100644
--- a/modules/ecm-esignature-logalty/pom.xml
+++ b/modules/ecm-esignature-logalty/pom.xml
@@ -7,13 +7,13 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
org.fireflyframework
fireflyframework-ecm-esignature-logalty
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - ECM eSignature - Logalty
diff --git a/modules/ecm-storage-aws/README.md b/modules/ecm-storage-aws/README.md
index 554ee5649..7fe7bafb2 100644
--- a/modules/ecm-storage-aws/README.md
+++ b/modules/ecm-storage-aws/README.md
@@ -20,7 +20,7 @@ Store an applicant's supporting document in Amazon S3 through the ECM content po
org.fireflyframework
fireflyframework-ecm-storage-aws
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm-storage-aws/pom.xml b/modules/ecm-storage-aws/pom.xml
index 15494d8be..8c0559d5a 100644
--- a/modules/ecm-storage-aws/pom.xml
+++ b/modules/ecm-storage-aws/pom.xml
@@ -7,13 +7,13 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
org.fireflyframework
fireflyframework-ecm-storage-aws
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - ECM Storage - AWS (S3)
diff --git a/modules/ecm-storage-azure/README.md b/modules/ecm-storage-azure/README.md
index ccb390f4f..31cdf441f 100644
--- a/modules/ecm-storage-azure/README.md
+++ b/modules/ecm-storage-azure/README.md
@@ -20,7 +20,7 @@ Store an applicant's supporting document in Azure Blob Storage through the ECM c
org.fireflyframework
fireflyframework-ecm-storage-azure
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm-storage-azure/pom.xml b/modules/ecm-storage-azure/pom.xml
index a3345a9dc..60ca6e109 100644
--- a/modules/ecm-storage-azure/pom.xml
+++ b/modules/ecm-storage-azure/pom.xml
@@ -7,13 +7,13 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
org.fireflyframework
fireflyframework-ecm-storage-azure
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - ECM Storage - Azure Blob
diff --git a/modules/ecm/README.md b/modules/ecm/README.md
index 5aa0e0fec..ab12b9c54 100644
--- a/modules/ecm/README.md
+++ b/modules/ecm/README.md
@@ -20,7 +20,7 @@ An applicant may upload supporting documents or sign an agreement after submissi
org.fireflyframework
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm/docs/adapters/docusign-integration-guide.md b/modules/ecm/docs/adapters/docusign-integration-guide.md
index f642266a3..435ace9e8 100644
--- a/modules/ecm/docs/adapters/docusign-integration-guide.md
+++ b/modules/ecm/docs/adapters/docusign-integration-guide.md
@@ -60,14 +60,14 @@ Add the DocuSign adapter dependency to your `pom.xml`:
org.fireflyframework
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
org.fireflyframework
fireflyframework-ecm-esignature-docusign
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm/docs/adapters/s3-integration-guide.md b/modules/ecm/docs/adapters/s3-integration-guide.md
index d726ba146..6b6b2eb24 100644
--- a/modules/ecm/docs/adapters/s3-integration-guide.md
+++ b/modules/ecm/docs/adapters/s3-integration-guide.md
@@ -26,14 +26,14 @@ Add the S3 adapter dependency to your `pom.xml`:
org.fireflyframework
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
org.fireflyframework
fireflyframework-ecm-storage-aws
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm/docs/configuration-reference.md b/modules/ecm/docs/configuration-reference.md
index 64493c679..93f7c05ae 100644
--- a/modules/ecm/docs/configuration-reference.md
+++ b/modules/ecm/docs/configuration-reference.md
@@ -57,7 +57,7 @@ Requires dependency: `fireflyframework-ecm-storage-aws`
org.fireflyframework
fireflyframework-ecm-storage-aws
- 26.10.21-SNAPSHOT
+ 26.10.22
```
@@ -134,7 +134,7 @@ Requires dependency: `fireflyframework-ecm-esignature-docusign`
org.fireflyframework
fireflyframework-ecm-esignature-docusign
- 26.10.21-SNAPSHOT
+ 26.10.22
```
@@ -163,7 +163,7 @@ Requires dependency: `fireflyframework-ecm-esignature-adobe-sign`
org.fireflyframework
fireflyframework-ecm-esignature-adobe-sign
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm/docs/configuration.md b/modules/ecm/docs/configuration.md
index f76f1895c..3d18cf2c3 100644
--- a/modules/ecm/docs/configuration.md
+++ b/modules/ecm/docs/configuration.md
@@ -18,14 +18,14 @@ Before configuring, ensure you have added the required dependencies:
org.fireflyframework
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
org.fireflyframework
fireflyframework-ecm-storage-aws
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/ecm/docs/guides/azure-integration.md b/modules/ecm/docs/guides/azure-integration.md
index addb6ea72..522d38ea9 100644
--- a/modules/ecm/docs/guides/azure-integration.md
+++ b/modules/ecm/docs/guides/azure-integration.md
@@ -51,7 +51,7 @@ Add the required dependencies to your `pom.xml`:
org.fireflyframework
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
diff --git a/modules/ecm/pom.xml b/modules/ecm/pom.xml
index fbcda69f6..5d5f03410 100644
--- a/modules/ecm/pom.xml
+++ b/modules/ecm/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-ecm
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - Enterprise Content Management Library
diff --git a/modules/eda-kafka/README.md b/modules/eda-kafka/README.md
index 76661ecd2..6ceea297f 100644
--- a/modules/eda-kafka/README.md
+++ b/modules/eda-kafka/README.md
@@ -20,7 +20,7 @@ Publish application lifecycle events to Kafka when a separate review worker cons
org.fireflyframework
fireflyframework-eda-kafka
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eda-kafka/pom.xml b/modules/eda-kafka/pom.xml
index 6b6916c77..6346f8687 100644
--- a/modules/eda-kafka/pom.xml
+++ b/modules/eda-kafka/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-eda-kafka
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - EDA - Kafka
diff --git a/modules/eda-postgres/README.md b/modules/eda-postgres/README.md
index 4de7254cc..d66b20799 100644
--- a/modules/eda-postgres/README.md
+++ b/modules/eda-postgres/README.md
@@ -20,7 +20,7 @@ A PostgreSQL delivery table can carry application lifecycle events without a sep
org.fireflyframework
fireflyframework-eda-postgres
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eda-postgres/pom.xml b/modules/eda-postgres/pom.xml
index bf6c6be7f..7da2066f2 100644
--- a/modules/eda-postgres/pom.xml
+++ b/modules/eda-postgres/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-eda-postgres
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - EDA - PostgreSQL
diff --git a/modules/eda-rabbitmq/README.md b/modules/eda-rabbitmq/README.md
index 8c760548b..ae5f34017 100644
--- a/modules/eda-rabbitmq/README.md
+++ b/modules/eda-rabbitmq/README.md
@@ -20,7 +20,7 @@ RabbitMQ can route application lifecycle events to the configured review queues.
org.fireflyframework
fireflyframework-eda-rabbitmq
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eda-rabbitmq/pom.xml b/modules/eda-rabbitmq/pom.xml
index 1313da966..b43b446c2 100644
--- a/modules/eda-rabbitmq/pom.xml
+++ b/modules/eda-rabbitmq/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-eda-rabbitmq
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - EDA - RabbitMQ
diff --git a/modules/eda/README.md b/modules/eda/README.md
index 8c2fb910d..25846acc8 100644
--- a/modules/eda/README.md
+++ b/modules/eda/README.md
@@ -20,7 +20,7 @@ Once a submitted application must notify another service, define an application.
org.fireflyframework
fireflyframework-eda
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eda/pom.xml b/modules/eda/pom.xml
index a87bef045..98b7fd332 100644
--- a/modules/eda/pom.xml
+++ b/modules/eda/pom.xml
@@ -7,7 +7,7 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
diff --git a/modules/eventsourcing/README.md b/modules/eventsourcing/README.md
index 735b6b648..953401aa7 100644
--- a/modules/eventsourcing/README.md
+++ b/modules/eventsourcing/README.md
@@ -20,7 +20,7 @@ If the product needs application history as the source of truth, model submitted
org.fireflyframework
fireflyframework-eventsourcing
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eventsourcing/docs/quick-start.md b/modules/eventsourcing/docs/quick-start.md
index 75cc98a86..944f6c118 100644
--- a/modules/eventsourcing/docs/quick-start.md
+++ b/modules/eventsourcing/docs/quick-start.md
@@ -15,7 +15,7 @@ Use event history to reconstruct an aggregate. In an onboarding service, that wo
org.fireflyframework
fireflyframework-eventsourcing
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/eventsourcing/pom.xml b/modules/eventsourcing/pom.xml
index 546e2049a..935a79fad 100644
--- a/modules/eventsourcing/pom.xml
+++ b/modules/eventsourcing/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-eventsourcing
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - Common Event Sourcing Library
diff --git a/modules/eventsourcing/src/main/resources/application.yml b/modules/eventsourcing/src/main/resources/application.yml
index a32c51f8d..502e3c9a6 100644
--- a/modules/eventsourcing/src/main/resources/application.yml
+++ b/modules/eventsourcing/src/main/resources/application.yml
@@ -125,7 +125,8 @@ spring:
r2dbc:
url: r2dbc:h2:mem:///testdb;DB_CLOSE_DELAY=-1;MODE=PostgreSQL
username: sa
- password: ""
+ # Supply an ephemeral credential when selecting this standalone test profile.
+ password: ${EVENT_STORE_TEST_PASSWORD}
flyway:
enabled: false # Managed by test setup
diff --git a/modules/eventsourcing/src/test/java/org/fireflyframework/eventsourcing/config/EventStoreTestCredentialsTest.java b/modules/eventsourcing/src/test/java/org/fireflyframework/eventsourcing/config/EventStoreTestCredentialsTest.java
new file mode 100644
index 000000000..f3b0e23ec
--- /dev/null
+++ b/modules/eventsourcing/src/test/java/org/fireflyframework/eventsourcing/config/EventStoreTestCredentialsTest.java
@@ -0,0 +1,46 @@
+package org.fireflyframework.eventsourcing.config;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.env.YamlPropertySourceLoader;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.mock.env.MockEnvironment;
+
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class EventStoreTestCredentialsTest {
+ private MockEnvironment testProfile() throws Exception {
+ var environment = new MockEnvironment();
+ var source = new YamlPropertySourceLoader().load("event-store", new ClassPathResource("application.yml"))
+ .stream().filter(value -> "test".equals(value.getProperty("spring.config.activate.on-profile")))
+ .findFirst().orElseThrow();
+ environment.getPropertySources().addLast(source);
+ return environment;
+ }
+
+ @Test
+ void testProfileHasNoImplicitEmptyCredential() throws Exception {
+ var environment = testProfile();
+ assertThrows(IllegalArgumentException.class, () -> environment.getProperty("spring.r2dbc.password"));
+ }
+
+ @Test
+ void explicitDynamicTestCredentialOverridesTheProfileWithoutAnEnvironmentSecret() throws Exception {
+ var environment = testProfile();
+ String credential = UUID.randomUUID().toString();
+ environment.setProperty("spring.r2dbc.password", credential);
+ assertEquals(credential, environment.getProperty("spring.r2dbc.password"));
+ }
+
+ @Test
+ void explicitTestCredentialResolvesWithoutChangingTheInMemoryTarget() throws Exception {
+ var environment = testProfile();
+ String credential = UUID.randomUUID().toString();
+ environment.setProperty("EVENT_STORE_TEST_PASSWORD", credential);
+ assertEquals(credential, environment.getProperty("spring.r2dbc.password"));
+ assertEquals("r2dbc:h2:mem:///testdb;DB_CLOSE_DELAY=-1;MODE=PostgreSQL", environment.getProperty("spring.r2dbc.url"));
+ assertEquals("sa", environment.getProperty("spring.r2dbc.username"));
+ assertEquals(Boolean.FALSE, environment.getProperty("spring.flyway.enabled", Boolean.class));
+ }
+}
diff --git a/modules/kernel/README.md b/modules/kernel/README.md
index 24171ff56..7258d67b1 100644
--- a/modules/kernel/README.md
+++ b/modules/kernel/README.md
@@ -20,7 +20,7 @@ A rejected application and an unavailable verification partner need different er
org.fireflyframework
fireflyframework-kernel
- 26.10.21-SNAPSHOT
+ 26.10.22
```
diff --git a/modules/kernel/pom.xml b/modules/kernel/pom.xml
index 2af3736c1..e0eea36fe 100644
--- a/modules/kernel/pom.xml
+++ b/modules/kernel/pom.xml
@@ -7,12 +7,12 @@
org.fireflyframework
fireflyframework-parent
- 26.10.21-SNAPSHOT
+ 26.10.22
../../build/parent/pom.xml
fireflyframework-kernel
- 26.10.21-SNAPSHOT
+ 26.10.22
jar
Firefly Framework - Kernel
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditActor.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditActor.java
new file mode 100644
index 000000000..14024f9a1
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditActor.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.util.UUID;
+
+/**
+ * Exact claimed actor identity. Trusted authentication adapters must supply and verify it.
+ * The platform tenant is the exact authenticated key, independent of the resource tenant UUID.
+ * Staff realm and stable staff ID are either both present or both absent.
+ */
+public record AuditActor(String issuer, String subject, String clientId, String platformTenantId,
+ String staffRealm, UUID staffId) {
+ public AuditActor {
+ AuditValidation.text(issuer);
+ AuditValidation.text(subject);
+ AuditValidation.text(clientId);
+ AuditValidation.text(platformTenantId);
+ if ((staffRealm == null) != (staffId == null))
+ throw new IllegalArgumentException("Incomplete audit staff identity");
+ if (staffRealm != null) AuditValidation.text(staffRealm);
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditCheckpoint.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditCheckpoint.java
new file mode 100644
index 000000000..2cedc2096
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditCheckpoint.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+/**
+ * A checkpoint value, not proof of its custody or signature. Verification callers must obtain
+ * non-genesis checkpoints from an independently trusted source, not the range being checked.
+ */
+public record AuditCheckpoint(AuditStream stream, long lastSequence, String lastHash) {
+ private static final String GENESIS_HASH = "0".repeat(64);
+
+ public AuditCheckpoint {
+ AuditValidation.required(stream);
+ AuditValidation.digest(lastHash);
+ if (lastSequence < 0 || (lastSequence == 0 && !GENESIS_HASH.equals(lastHash)))
+ throw new IllegalArgumentException("Invalid audit checkpoint sequence");
+ }
+
+ public static AuditCheckpoint genesis(AuditStream stream) {
+ return new AuditCheckpoint(stream, 0, GENESIS_HASH);
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvent.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvent.java
new file mode 100644
index 000000000..9c3063bcf
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvent.java
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Bounded business evidence metadata, without arbitrary payloads or secrets.
+ * Identity, outcome, time and evidence digest require verification by the owning service.
+ * A null causation ID identifies a root event; other links remain explicit.
+ */
+public record AuditEvent(UUID eventId, AuditStream stream, AuditActor actor, String action, Outcome outcome,
+ UUID processId, UUID correlationId, UUID causationId, Instant occurredAt,
+ String evidenceDigest, String policyRevision) {
+ public enum Outcome { ATTEMPTED, ACCEPTED, REJECTED, FAILED, CANCELLED, COMPLETED, UNKNOWN }
+
+ public AuditEvent {
+ AuditValidation.required(eventId);
+ AuditValidation.required(stream);
+ AuditValidation.required(actor);
+ AuditValidation.token(action);
+ AuditValidation.required(outcome);
+ AuditValidation.required(processId);
+ AuditValidation.required(correlationId);
+ AuditValidation.required(occurredAt);
+ AuditValidation.digest(evidenceDigest);
+ AuditValidation.token(policyRevision);
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvidenceVerifier.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvidenceVerifier.java
new file mode 100644
index 000000000..32c8d37f9
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditEvidenceVerifier.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.util.List;
+
+/** Evidence integrity between trusted checkpoints; never an authorization or durability check. */
+public interface AuditEvidenceVerifier {
+ int MAX_RANGE_RECORDS = 1000;
+
+ /**
+ * Verifies a complete, ordered range of at most {@value #MAX_RANGE_RECORDS} records.
+ * Event identity uniqueness outside this range must be enforced by the durable store.
+ * @throws IllegalArgumentException if the range is invalid or inconsistent
+ */
+ void verify(AuditCheckpoint trustedStart, AuditCheckpoint trustedEnd, List records);
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecord.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecord.java
new file mode 100644
index 000000000..bef3f3fe5
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecord.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.time.Instant;
+
+/** Unverified immutable evidence value; construction does not attest persistence or hash correctness. */
+public record AuditRecord(AuditEvent event, long sequence, Instant recordedAt,
+ String previousHash, String recordHash) {
+ public AuditRecord {
+ AuditValidation.required(event);
+ AuditValidation.required(recordedAt);
+ AuditValidation.digest(previousHash);
+ AuditValidation.digest(recordHash);
+ if (sequence < 1) throw new IllegalArgumentException("Invalid audit record sequence");
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecordHasher.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecordHasher.java
new file mode 100644
index 000000000..1311bc6fa
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditRecordHasher.java
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.io.ByteArrayOutputStream;
+import java.io.DataOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.time.Instant;
+import java.util.HexFormat;
+import java.util.UUID;
+
+/**
+ * Pure canonical SHA-256 evidence construction. Does not reserve sequence numbers, append data,
+ * sign a checkpoint, validate actor claims or establish an immutable storage boundary.
+ */
+public final class AuditRecordHasher {
+ private AuditRecordHasher() { }
+
+ public static AuditRecord record(AuditCheckpoint previous, AuditEvent event, Instant recordedAt) {
+ AuditValidation.required(previous);
+ AuditValidation.required(event);
+ AuditValidation.required(recordedAt);
+ if (!previous.stream().equals(event.stream()) || previous.lastSequence() == Long.MAX_VALUE)
+ throw new IllegalArgumentException("Invalid audit stream or exhausted sequence");
+ long sequence = previous.lastSequence() + 1;
+ try {
+ var bytes = new ByteArrayOutputStream();
+ var out = new DataOutputStream(bytes);
+ text(out, "firefly.audit.record");
+ out.writeInt(1);
+ uuid(out, event.stream().resourceTenantId());
+ text(out, event.stream().service());
+ text(out, event.stream().resourceType());
+ uuid(out, event.stream().resourceId());
+ out.writeLong(sequence);
+ text(out, previous.lastHash());
+ instant(out, recordedAt);
+ uuid(out, event.eventId());
+ text(out, event.actor().issuer());
+ text(out, event.actor().subject());
+ text(out, event.actor().clientId());
+ text(out, event.actor().platformTenantId());
+ out.writeBoolean(event.actor().staffId() != null);
+ if (event.actor().staffId() != null) {
+ text(out, event.actor().staffRealm());
+ uuid(out, event.actor().staffId());
+ }
+ text(out, event.action());
+ text(out, event.outcome().name());
+ uuid(out, event.processId());
+ uuid(out, event.correlationId());
+ out.writeBoolean(event.causationId() != null);
+ if (event.causationId() != null) uuid(out, event.causationId());
+ instant(out, event.occurredAt());
+ text(out, event.evidenceDigest());
+ text(out, event.policyRevision());
+ out.flush();
+ String hash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes.toByteArray()));
+ return new AuditRecord(event, sequence, recordedAt, previous.lastHash(), hash);
+ } catch (IOException | NoSuchAlgorithmException exception) {
+ throw new IllegalStateException("Audit evidence encoding is unavailable", exception);
+ }
+ }
+
+ private static void text(DataOutputStream out, String value) throws IOException {
+ byte[] bytes = value.getBytes(StandardCharsets.UTF_8);
+ out.writeInt(bytes.length);
+ out.write(bytes);
+ }
+
+ private static void uuid(DataOutputStream out, UUID value) throws IOException {
+ out.writeLong(value.getMostSignificantBits());
+ out.writeLong(value.getLeastSignificantBits());
+ }
+
+ private static void instant(DataOutputStream out, Instant value) throws IOException {
+ out.writeLong(value.getEpochSecond());
+ out.writeInt(value.getNano());
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditStream.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditStream.java
new file mode 100644
index 000000000..ea5cdc965
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditStream.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.util.UUID;
+
+/** An evidence stream scope, never a grant of access to its resource. */
+public record AuditStream(UUID resourceTenantId, String service, String resourceType, UUID resourceId) {
+ public AuditStream {
+ AuditValidation.required(resourceTenantId);
+ AuditValidation.token(service);
+ AuditValidation.token(resourceType);
+ AuditValidation.required(resourceId);
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditValidation.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditValidation.java
new file mode 100644
index 000000000..ad79978f2
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/AuditValidation.java
@@ -0,0 +1,60 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Objects;
+import java.util.regex.Pattern;
+
+final class AuditValidation {
+ private static final Pattern TOKEN = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}");
+ private static final Pattern DIGEST = Pattern.compile("[0-9a-f]{64}");
+
+ private AuditValidation() { }
+
+ static T required(T value) {
+ return Objects.requireNonNull(value, "Required audit field is absent");
+ }
+
+ static String token(String value) {
+ if (!TOKEN.matcher(required(value)).matches()) throw new IllegalArgumentException("Invalid audit token");
+ return value;
+ }
+
+ static String digest(String value) {
+ if (!DIGEST.matcher(required(value)).matches()) throw new IllegalArgumentException("Invalid audit digest");
+ return value;
+ }
+
+ static String text(String value) {
+ required(value);
+ if (value.isBlank() || value.length() > 2048) throw new IllegalArgumentException("Invalid audit text");
+ for (int i = 0; i < value.length(); i++) {
+ char c = value.charAt(i);
+ if (Character.isISOControl(c) || c == '\u2028' || c == '\u2029')
+ throw new IllegalArgumentException("Invalid audit text");
+ if (Character.isHighSurrogate(c)) {
+ if (++i >= value.length() || !Character.isLowSurrogate(value.charAt(i)))
+ throw new IllegalArgumentException("Invalid audit text");
+ } else if (Character.isLowSurrogate(c)) {
+ throw new IllegalArgumentException("Invalid audit text");
+ }
+ }
+ if (value.getBytes(StandardCharsets.UTF_8).length > 2048)
+ throw new IllegalArgumentException("Invalid audit text");
+ return value;
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/impl/Sha256AuditEvidenceVerifier.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/impl/Sha256AuditEvidenceVerifier.java
new file mode 100644
index 000000000..7753b45dd
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/impl/Sha256AuditEvidenceVerifier.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.fireflyframework.kernel.audit.impl;
+
+import org.fireflyframework.kernel.audit.AuditCheckpoint;
+import org.fireflyframework.kernel.audit.AuditEvidenceVerifier;
+import org.fireflyframework.kernel.audit.AuditRecord;
+import org.fireflyframework.kernel.audit.AuditRecordHasher;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.UUID;
+
+public final class Sha256AuditEvidenceVerifier implements AuditEvidenceVerifier {
+ @Override
+ public void verify(AuditCheckpoint trustedStart, AuditCheckpoint trustedEnd, List records) {
+ Objects.requireNonNull(trustedStart, "Required audit checkpoint is absent");
+ Objects.requireNonNull(trustedEnd, "Required audit checkpoint is absent");
+ Objects.requireNonNull(records, "Required audit range is absent");
+ long count = trustedEnd.lastSequence() - trustedStart.lastSequence();
+ if (!trustedStart.stream().equals(trustedEnd.stream()) || count < 0 || count > MAX_RANGE_RECORDS
+ || records.size() != count)
+ throw new IllegalArgumentException("Invalid audit range bounds");
+ List snapshot = List.copyOf(records);
+ var identities = new HashSet();
+ AuditCheckpoint previous = trustedStart;
+ for (AuditRecord record : snapshot) {
+ AuditRecord expected = AuditRecordHasher.record(previous, record.event(), record.recordedAt());
+ if (record.sequence() != expected.sequence() || !record.previousHash().equals(expected.previousHash())
+ || !record.recordHash().equals(expected.recordHash()) || !identities.add(record.event().eventId()))
+ throw new IllegalArgumentException("Audit range integrity mismatch");
+ previous = new AuditCheckpoint(record.event().stream(), record.sequence(), record.recordHash());
+ }
+ if (!previous.equals(trustedEnd)) throw new IllegalArgumentException("Audit terminal checkpoint mismatch");
+ }
+}
diff --git a/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/package-info.java b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/package-info.java
new file mode 100644
index 000000000..edf5b16f9
--- /dev/null
+++ b/modules/kernel/src/main/java/org/fireflyframework/kernel/audit/package-info.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2024-2026 Firefly Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Immutable audit evidence values and bounded integrity verification. These types do not append
+ * records, authenticate actors, establish retention, or prove that business operations were audited.
+ * Owners must persist evidence atomically with each applicable local business effect and obtain
+ * verification checkpoints from independent custody. The existing security logging SPI is separate.
+ *
+ *