feat: support for multiple independent named contexts

Signed-off-by: Leo Galambos <lg@hq.egothor.org>

.classpath

@@ -6,12 +6,6 @@
 			<attribute name="gradle_used_by_scope" value="main,test"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="src" output="bin/main" path="src/main/resources">
-		<attributes>
-			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
-		</attributes>
-	</classpathentry>
 	<classpathentry kind="src" output="bin/test" path="src/test/java">
 		<attributes>
 			<attribute name="gradle_scope" value="test"/>
@@ -19,13 +13,6 @@
 			<attribute name="test" value="true"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="src" output="bin/test" path="src/test/resources">
-		<attributes>
-			<attribute name="gradle_scope" value="test"/>
-			<attribute name="gradle_used_by_scope" value="test"/>
-			<attribute name="test" value="true"/>
-		</attributes>
-	</classpathentry>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-21/"/>
 	<classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
 	<classpathentry kind="output" path="bin/default"/>

.gitea/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'release@*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - name: Cache Gradle
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Build and publish to Gitea Maven
+        run: ./gradlew clean publish --no-daemon -PgiteaToken=${{ secrets.CI_PUBLISH_TOKEN }}
+
+      - name: Upload built JAR
+        uses: actions/upload-artifact@v3
+        with:
+          name: conflux
+          path: build/libs/*.jar
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          current_tag="${{ github.ref_name }}"
+
+          # strip the prefix for sorting, keep prefix for matching
+          prefix="release@"
+
+          # get all matching tags, strip prefix, sort them
+          all_versions=$(git tag --list "${prefix}*" | sed "s/^${prefix}//" | sort -V)
+
+          # find previous version
+          previous_tag=""
+          for v in $all_versions; do
+            if [[ "$prefix$v" == "$current_tag" ]]; then
+              break
+            fi
+            previous_tag="$prefix$v"
+          done
+
+          if [[ -z "$previous_tag" ]]; then
+            range=""
+          else
+            range="$previous_tag..$current_tag"
+          fi
+
+          echo "Comparing range: $range"
+
+          body="## What's New"
+
+          for category in "feat: Features" "fix: Bug Fixes" "docs: Documentation" "chore: Chores"; do
+            prefix="${category%%:*}"
+            title="${category##*: }"
+            entries=$(git log $range --pretty=format:"- %s" --grep="^$prefix" --no-merges)
+          # echo -e "Found:\n\n$entries\n\n"
+            if [[ -n "$entries" ]]; then
+              body="$body\n\n### $title\n$entries"
+            fi
+          done
+
+          echo -e "$body" > /tmp/release_notes.md
+
+      - name: Create Gitea Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: build/libs/*.jar
+          body_path: /tmp/release_notes.md

.gitea/workflows/tag.yml

@@ -0,0 +1,65 @@
+name: Tag version
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Which part to bump?"
+        required: true
+        default: "patch"
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          echo "${{ secrets.CI_BOT_GPG_PRIVATE_KEY }}" | gpg --import --batch --yes
+          # set trust non-interactively
+          echo "${{ secrets.CI_BOT_GPG_FINGERPRINT }}:5:" | gpg --import-ownertrust
+          git config --global user.signingkey $GPG_KEY_ID
+          git config --global commit.gpgSign true
+          git config --global tag.gpgSign true
+          git config user.name "Gitea CI"
+          git config user.email "gitea-ci@hq.egothor.org"
+          git remote set-url origin https://ci-bot:${GITEA_PUSH_TOKEN}@gitea.egothor.org/Egothor/conflux.git
+        env:
+          GITEA_PUSH_TOKEN: ${{ secrets.CI_PUSH_TOKEN }}
+          GPG_KEY_ID: ${{ secrets.CI_BOT_GPG_KEY_ID }}
+
+      - name: Bump version and tag
+        run: |
+          latest=$(git tag --list 'conflux@*' | sed 's/conflux@//' | sort -V | tail -n 1)
+          if [[ -z "$latest" ]]; then
+            latest="0.0.0"
+          fi
+          echo "Latest: $latest"
+          IFS='.' read -r major minor patch <<<"$latest"
+          case "${{ github.event.inputs.bump }}" in
+            major)
+              major=$((major+1)); minor=0; patch=0 ;;
+            minor)
+              minor=$((minor+1)); patch=0 ;;
+            patch)
+              patch=$((patch+1)) ;;
+            *)
+              echo "Invalid bump type"
+              exit 1
+              ;;
+          esac
+          next="$major.$minor.$patch"
+          new_tag="release@$next"
+          git tag -s $new_tag -m "Release $new_tag"
+          git push origin $new_tag
+          echo "Tagged $new_tag"

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 group 'org.egothor'
-version gitVersion(prefix:'conflux@')
+version gitVersion(prefix:'release@')
 
 repositories {
     // Use Maven Central for resolving dependencies.
@@ -25,6 +25,9 @@ java {
     toolchain {
         languageVersion = JavaLanguageVersion.of(21)
     }
+
+    withJavadocJar()
+    withSourcesJar()
 }
 
 javadoc {
@@ -36,7 +39,12 @@ tasks.named('test') {
     useJUnitPlatform()
 }
 
-publishing {
+tasks.withType(Javadoc).configureEach {
+    options.bottom = "Copyright © 2025 Egothor"
+}
+
+if (project.hasProperty('giteaToken') && project.giteaToken) {
+    publishing {
         publications {
             mavenJava(MavenPublication) {
                 from components.java
@@ -57,6 +65,9 @@ publishing {
                 }
             }
         }
+    }
+} else {
+    println "No giteaToken defined - skipping publishing configuration"
 }
 
 gradle.taskGraph.whenReady { taskGraph ->

gradle/libs.versions.toml

@@ -1,12 +1,7 @@
-# This file was generated by the Gradle 'init' task.
 # https://docs.gradle.org/current/userguide/platforms.html#sub::toml-dependencies-format
 
 [versions]
-commons-math3 = "3.6.1"
-guava = "33.1.0-jre"
 junit-jupiter = "5.10.2"
 
 [libraries]
-commons-math3 = { module = "org.apache.commons:commons-math3", version.ref = "commons-math3" }
-guava = { module = "com.google.guava:guava", version.ref = "guava" }
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }

src/main/java/conflux/Ctx.java

@@ -34,169 +34,133 @@
  */
 package conflux;
 
-import java.lang.ref.WeakReference;
-import java.util.List;
 import java.util.Map;
-import java.util.Objects;
+import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
- * A globally accessible, type-safe context for sharing data between independent
+ * A central context manager for storing and retrieving key-value pairs in a
- * parts of an application. Supports listeners that are notified whenever a
+ * thread-safe, type-safe manner.
- * registered key's value changes.
  * 
- * This implementation guarantees:
+ * This enum serves as both:
  * <ul>
- * <li>Strongly typed keys using {@link Key}</li>
+ * <li>A singleton context via {@code Ctx.INSTANCE} for global/shared usage</li>
- * <li>One consistent type per key name</li>
+ * <li>A factory and registry for multiple named independent contexts</li>
- * <li>Support for weak-referenced listeners to avoid memory leaks</li>
- * <li>Thread-safe operations</li>
  * </ul>
  * 
- * Usage:
+ * Each context provides listener support for reactive value changes.
  *
- * <pre>
+ * @see Key
- * Key<Integer> COUNT = Key.of("count", Integer.class);
+ * @see Listener
- * Ctx.INSTANCE.put(COUNT, 42);
- * int v = Ctx.INSTANCE.get(COUNT);
- * </pre>
  * 
  * @author Leo Galambos
  */
-public enum Ctx {
+public enum Ctx implements CtxInterface {
     /**
-     * Singleton instance of the context.
+     * The singleton instance representing the default/global context.
      */
     INSTANCE;
 
-    private final Map<Key<?>, Object> values = new ConcurrentHashMap<>();
+    /**
-    private final Map<String, Class<?>> keyTypes = new ConcurrentHashMap<>();
+     * A registry of named contexts, allowing for multiple isolated logical
-    private final Map<Key<?>, List<WeakReference<Listener<?>>>> listeners = new ConcurrentHashMap<>();
+     * contexts.
+     */
+    private final Map<String, CtxInterface> contexts = new ConcurrentHashMap<>();
+    /**
+     * The default context instance used by this enum singleton. All interface
+     * method calls delegate to this context.
+     */
+    private final CtxInterface defaultCtx = new CtxInstance();
 
     /**
-     * Stores or updates the value for a given key. If the key is used for the first
+     * Returns a named context. If the context does not exist, it is lazily created.
-     * time, its type is recorded. If the key has been used before with a different
-     * type, an exception will be thrown.
      * 
-     * After setting the value, any registered listeners for that key will be
+     * This method allows isolation between different logical scopes (e.g.,
-     * notified (if the value was modified).
+     * sessions, users).
      *
-     * @param key   the key
+     * @param name the name of the context
-     * @param value the value to store
+     * @return the associated context instance
-     * @param <T>   the type of the value
-     * @throws IllegalStateException if the key is reused with a different type
      */
+    public CtxInterface getContext(String name) {
+        return contexts.computeIfAbsent(name, k -> new CtxInstance());
+    }
+
+    /**
+     * Returns the set of names for all currently registered contexts.
+     *
+     * @return an immutable set of context names
+     */
+    public Set<String> contextNames() {
+        return Set.copyOf(contexts.keySet());
+    }
+
+    /**
+     * {@inheritDoc}
+     * 
+     * Delegates to the default context instance.
+     */
+    @Override
     public <T> void put(Key<T> key, T value) {
-        keyTypes.compute(key.name(), (k, existingType) -> {
+        defaultCtx.put(key, value);
-            if (existingType == null) {
-                return key.type();
-            } else {
-                if (!existingType.equals(key.type())) {
-                    throw new IllegalStateException(
-                            "Key '" + key.name() + "' already associated with type " + existingType.getName());
-                }
-                return existingType;
-            }
-        });
-
-        @SuppressWarnings("unchecked")
-        T previous = (T) values.put(key, value);
-
-        if (Objects.deepEquals(value, previous)) {
-            // no change
-            return;
-        }
-
-        // notify listeners
-        var list = listeners.get(key);
-        if (list != null) {
-            for (var ref : list) {
-                var listener = ref.get();
-                if (listener != null) {
-                    @SuppressWarnings("unchecked")
-                    Listener<T> typedListener = (Listener<T>) listener;
-                    typedListener.valueChanged(value);
-                }
-            }
-            // clean up dead weak references
-            list.removeIf(ref -> ref.get() == null);
-        }
     }
 
     /**
-     * Retrieves the value for the given key, or {@code null} if not set.
+     * {@inheritDoc}
      * 
-     * @param key the key
+     * Delegates to the default context instance.
-     * @param <T> the type
-     * @return the stored value or null
      */
-    @SuppressWarnings("unchecked")
+    @Override
     public <T> T get(Key<T> key) {
-        return (T) values.get(key);
+        return defaultCtx.get(key);
     }
 
     /**
-     * Checks if a value exists for the given key.
+     * {@inheritDoc}
      * 
-     * @param key the key
+     * Delegates to the default context instance.
-     * @return true if a value is present
      */
+    @Override
     public boolean contains(Key<?> key) {
-        return values.containsKey(key);
+        return defaultCtx.contains(key);
     }
 
     /**
-     * Removes the value and any listeners for the given key.
+     * {@inheritDoc}
      * 
-     * @param key the key
+     * Delegates to the default context instance.
-     * @return the removed value, or null if absent
      */
+    @Override
     public Object remove(Key<?> key) {
-        keyTypes.remove(key.name());
+        return defaultCtx.remove(key);
-        var removed = values.remove(key);
-        listeners.remove(key);
-        return removed;
     }
 
     /**
-     * Clears all keys and listeners from the context.
+     * {@inheritDoc}
+     * 
+     * Delegates to the default context instance.
      */
+    @Override
     public void clear() {
-        values.clear();
+        defaultCtx.clear();
-        keyTypes.clear();
-        listeners.clear();
     }
 
     /**
-     * Registers a listener to be notified whenever the value for the key changes.
+     * {@inheritDoc}
-     * The listener is weakly referenced to avoid preventing its garbage collection.
      * 
-     * @param key      the key
+     * Delegates to the default context instance.
-     * @param listener the listener
-     * @param <T>      the type
      */
+    @Override
     public <T> void addListener(Key<T> key, Listener<T> listener) {
-        listeners.computeIfAbsent(key, k -> new CopyOnWriteArrayList<>()).add(new WeakReference<>(listener));
+        defaultCtx.addListener(key, listener);
     }
 
     /**
-     * Unregisters a previously registered listener for the key.
+     * {@inheritDoc}
      * 
-     * @param key      the key
+     * Delegates to the default context instance.
-     * @param listener the listener to remove
-     * @param <T>      the type
      */
+    @Override
     public <T> void removeListener(Key<T> key, Listener<T> listener) {
-        var list = listeners.get(key);
+        defaultCtx.removeListener(key, listener);
-        if (list != null) {
-            list.removeIf(ref -> {
-                var l = ref.get();
-                return l == null || l.equals(listener);
-            });
-            if (list.isEmpty()) {
-                listeners.remove(key);
-            }
-        }
     }
 }

src/main/java/conflux/CtxInstance.java

@@ -0,0 +1,197 @@
+/**
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package conflux;
+
+import java.lang.ref.WeakReference;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * A globally accessible, type-safe context for sharing data between independent
+ * parts of an application. Supports listeners that are notified whenever a
+ * registered key's value changes.
+ *
+ * This implementation guarantees:
+ * <ul>
+ * <li>Strongly typed keys using {@link Key}</li>
+ * <li>One consistent type per key name</li>
+ * <li>Support for weak-referenced listeners to avoid memory leaks</li>
+ * <li>Thread-safe operations</li>
+ * </ul>
+ *
+ * @author Leo Galambos
+ */
+public final class CtxInstance implements CtxInterface {
+
+    private final Map<Key<?>, Object> values = new ConcurrentHashMap<>();
+    private final Map<String, Class<?>> keyTypes = new ConcurrentHashMap<>();
+    private final Map<Key<?>, List<WeakReference<Listener<?>>>> listeners = new ConcurrentHashMap<>();
+
+    /**
+     * Stores or updates the value for a given key. If the key is used for the first
+     * time, its type is recorded. If the key has been used before with a different
+     * type, an exception will be thrown.
+     *
+     * After setting the value, any registered listeners for that key will be
+     * notified (if the value was modified).
+     *
+     * @param key   the key
+     * @param value the value to store
+     * @param <T>   the type of the value
+     * @throws IllegalStateException if the key is reused with a different type
+     */
+    @Override
+    public <T> void put(Key<T> key, T value) {
+        keyTypes.compute(key.name(), (k, existingType) -> {
+            if (existingType == null) {
+                return key.type();
+            } else {
+                if (!existingType.equals(key.type())) {
+                    throw new IllegalStateException(
+                            "Key '" + key.name() + "' already associated with type " + existingType.getName());
+                }
+                return existingType;
+            }
+        });
+
+        @SuppressWarnings("unchecked")
+        T previous = (T) values.put(key, value);
+
+        if (Objects.deepEquals(value, previous)) {
+            // no change
+            return;
+        }
+
+        // notify listeners
+        var list = listeners.get(key);
+        if (list != null) {
+            for (var ref : list) {
+                var listener = ref.get();
+                if (listener != null) {
+                    @SuppressWarnings("unchecked")
+                    Listener<T> typedListener = (Listener<T>) listener;
+                    typedListener.valueChanged(value);
+                }
+            }
+            // clean up dead weak references
+            list.removeIf(ref -> ref.get() == null);
+        }
+    }
+
+    /**
+     * Retrieves the value for the given key, or {@code null} if not set.
+     *
+     * @param key the key
+     * @param <T> the type
+     * @return the stored value or null
+     */
+    @Override
+    @SuppressWarnings("unchecked")
+    public <T> T get(Key<T> key) {
+        return (T) values.get(key);
+    }
+
+    /**
+     * Checks if a value exists for the given key.
+     *
+     * @param key the key
+     * @return true if a value is present
+     */
+    @Override
+    public boolean contains(Key<?> key) {
+        return values.containsKey(key);
+    }
+
+    /**
+     * Removes the value and any listeners for the given key.
+     *
+     * @param key the key
+     * @return the removed value, or null if absent
+     */
+    @Override
+    public Object remove(Key<?> key) {
+        keyTypes.remove(key.name());
+        var removed = values.remove(key);
+        listeners.remove(key);
+        return removed;
+    }
+
+    /**
+     * Clears all keys and listeners from the context.
+     */
+    @Override
+    public void clear() {
+        values.clear();
+        keyTypes.clear();
+        listeners.clear();
+    }
+
+    /**
+     * Registers a listener to be notified whenever the value for the key changes.
+     * The listener is weakly referenced to avoid preventing its garbage collection.
+     *
+     * @param key      the key
+     * @param listener the listener
+     * @param <T>      the type
+     */
+    @Override
+    public <T> void addListener(Key<T> key, Listener<T> listener) {
+        listeners.computeIfAbsent(key, k -> new CopyOnWriteArrayList<>()).add(new WeakReference<>(listener));
+    }
+
+    /**
+     * Unregisters a previously registered listener for the key.
+     *
+     * @param key      the key
+     * @param listener the listener to remove
+     * @param <T>      the type
+     */
+    @Override
+    public <T> void removeListener(Key<T> key, Listener<T> listener) {
+        var list = listeners.get(key);
+        if (list != null) {
+            list.removeIf(ref -> {
+                var l = ref.get();
+                return l == null || l.equals(listener);
+            });
+            if (list.isEmpty()) {
+                listeners.remove(key);
+            }
+        }
+    }
+}

src/main/java/conflux/CtxInterface.java

@@ -0,0 +1,121 @@
+/**
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+package conflux;
+
+/**
+ * A type-safe, thread-safe context interface for storing and retrieving
+ * key-value pairs.
+ *
+ * Implementations of this interface support:
+ * <ul>
+ * <li>Recording type-safe associations between keys and values</li>
+ * <li>Automatic listener notification when a value changes</li>
+ * <li>Context isolation (e.g., per name or use case)</li>
+ * </ul>
+ *
+ * This interface is sealed to only permit known, safe implementations.
+ *
+ * @see Key
+ * @see Listener
+ * 
+ * @author Leo Galambos
+ */
+public sealed interface CtxInterface permits Ctx, CtxInstance {
+
+    /**
+     * Stores or updates the value for a given key. If the key is used for the first
+     * time, its type is recorded. If the key has been used before with a different
+     * type, an exception will be thrown.
+     *
+     * After setting the value, any registered listeners for that key will be
+     * notified (if the value was modified).
+     *
+     * @param key   the key
+     * @param value the value to store
+     * @param <T>   the type of the value
+     * @throws IllegalStateException if the key is reused with a different type
+     */
+    <T> void put(Key<T> key, T value);
+
+    /**
+     * Retrieves the value for the given key, or {@code null} if not set.
+     *
+     * @param key the key
+     * @param <T> the type
+     * @return the stored value or null
+     */
+    <T> T get(Key<T> key);
+
+    /**
+     * Checks if a value exists for the given key.
+     *
+     * @param key the key
+     * @return true if a value is present
+     */
+    boolean contains(Key<?> key);
+
+    /**
+     * Removes the value and any listeners for the given key.
+     *
+     * @param key the key
+     * @return the removed value, or null if absent
+     */
+    Object remove(Key<?> key);
+
+    /**
+     * Clears all keys and listeners from the context.
+     */
+    void clear();
+
+    /**
+     * Registers a listener to be notified whenever the value for the key changes.
+     * The listener is weakly referenced to avoid preventing its garbage collection.
+     *
+     * @param key      the key
+     * @param listener the listener
+     * @param <T>      the type
+     */
+    <T> void addListener(Key<T> key, Listener<T> listener);
+
+    /**
+     * Unregisters a previously registered listener for the key.
+     *
+     * @param key      the key
+     * @param listener the listener to remove
+     * @param <T>      the type
+     */
+    <T> void removeListener(Key<T> key, Listener<T> listener);
+
+}

src/main/java/conflux/package-info.java

@@ -0,0 +1,37 @@
+/**
+ * Provides a lightweight, type-safe, application-wide context mechanism for
+ * sharing strongly typed data among otherwise decoupled classes.
+ *
+ * The {@link conflux.Ctx} enum serves as a central, generic context storage,
+ * supporting key-based put/get operations. Each {@link conflux.Key} instance
+ * defines a unique, strongly typed entry in the context, ensuring type
+ * consistency and preventing misuse.
+ *
+ * The {@link conflux.Listener} interface allows clients to observe value
+ * changes for specific keys. Listeners are weakly referenced to prevent memory
+ * leaks.
+ *
+ * Typical usage:
+ * <ul>
+ * <li>Define {@link conflux.Key} instances with explicit types</li>
+ * <li>Store values via {@code Ctx.INSTANCE.put(key, value)}</li>
+ * <li>Retrieve values via {@code Ctx.INSTANCE.get(key)}</li>
+ * <li>Register listeners with {@code Ctx.INSTANCE.addListener()}</li>
+ * </ul>
+ *
+ * Values and listeners can be removed individually, or the entire context can
+ * be cleared.
+ *
+ * Best practices:
+ * <ul>
+ * <li>Define keys as constants to maintain consistency and avoid
+ * collisions</li>
+ * <li>Remove listeners when no longer needed</li>
+ * <li>Use unique key names to avoid accidental type conflicts</li>
+ * </ul>
+ *
+ * @see conflux.Ctx
+ * @see conflux.Key
+ * @see conflux.Listener
+ */
+package conflux;

src/test/java/conflux/CtxTest.java

@@ -36,6 +36,7 @@ package conflux;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -159,4 +160,50 @@ public class CtxTest {
         assertTrue(flag[0] || !flag[0]);
         System.out.println("...ok");
     }
+
+    @Test
+    void testMultipleContextsIsolation() {
+        System.out.println("testMultipleContextsIsolation");
+        var ctxA = Ctx.INSTANCE.getContext("A");
+        var ctxB = Ctx.INSTANCE.getContext("B");
+
+        ctxA.put(intKey, 10);
+        ctxB.put(intKey, 20);
+
+        assertEquals(10, ctxA.get(intKey));
+        assertEquals(20, ctxB.get(intKey));
+        assertNull(Ctx.INSTANCE.get(intKey)); // Default context is separate
+
+        ctxA.clear();
+        assertFalse(ctxA.contains(intKey));
+        assertEquals(20, ctxB.get(intKey));
+
+        System.out.println("...ok");
+    }
+
+    @Test
+    void testListenerNotificationInSeparateContexts() {
+        System.out.println("testListenerNotificationInSeparateContexts");
+        var ctxA = Ctx.INSTANCE.getContext("A");
+        var ctxB = Ctx.INSTANCE.getContext("B");
+
+        var resultA = new StringBuilder();
+        var resultB = new StringBuilder();
+
+        Listener<Integer> listenerA = v -> resultA.append(v);
+        Listener<Integer> listenerB = v -> resultB.append(v);
+
+        ctxA.addListener(intKey, listenerA);
+        ctxB.addListener(intKey, listenerB);
+
+        ctxA.put(intKey, 1);
+        ctxB.put(intKey, 2);
+        ctxA.put(intKey, 3);
+        ctxB.put(intKey, 4);
+
+        assertEquals("13", resultA.toString());
+        assertEquals("24", resultB.toString());
+
+        System.out.println("...ok");
+    }
 }