sirius-framework-mcp 0.1.0

package/dist/resources/db/queries.md

@@ -0,0 +1,178 @@
+# Queries
+
+Sirius-db provides a consistent query builder pattern across all three database
+backends. Each mapper has its own `select()` method that returns a typed query
+object, but the API surface is deliberately similar.
+
+## OMA — JDBC Queries (SmartQuery)
+
+`OMA` is the mapper for `SQLEntity`. Inject it with `@Part`:
+
+```java
+@Part
+private OMA oma;
+```
+
+**Select (query builder):**
+```java
+SmartQuery<Product> query = oma.select(Product.class)
+                               .eq(Product.CATEGORY, "electronics")
+                               .orderAsc(Product.NAME)
+                               .limit(50);
+
+List<Product> products = query.queryList();
+```
+
+**Find by ID:**
+```java
+Optional<Product> product = oma.find(Product.class, productId);
+```
+
+**Count:**
+```java
+long count = oma.select(Product.class)
+                .eq(Product.ACTIVE, true)
+                .count();
+```
+
+**Exists check:**
+```java
+boolean exists = oma.select(Product.class)
+                    .eq(Product.SKU, sku)
+                    .exists();
+```
+
+**Iteration (streaming):**
+```java
+oma.select(Product.class)
+   .eq(Product.ACTIVE, true)
+   .iterateAll(product -> {
+       // process each product
+   });
+```
+
+**Update and delete:**
+```java
+oma.update(product);
+oma.delete(product);
+oma.forceDelete(product);  // bypasses REJECT constraints
+```
+
+## Mango — MongoDB Queries (MongoQuery)
+
+`Mango` is the mapper for `MongoEntity`:
+
+```java
+@Part
+private Mango mango;
+```
+
+**Select:**
+```java
+MongoQuery<MongoProduct> query = mango.select(MongoProduct.class)
+                                      .eq(MongoProduct.CATEGORY, "electronics")
+                                      .orderAsc(MongoProduct.NAME)
+                                      .limit(50);
+
+List<MongoProduct> products = query.queryList();
+```
+
+**Find by ID:**
+```java
+Optional<MongoProduct> product = mango.find(MongoProduct.class, productId);
+```
+
+The query API mirrors OMA: `count()`, `exists()`, `iterateAll()`, `queryList()`,
+`queryFirst()`, `delete()`, and `update()` all work the same way.
+
+## Elastic — Elasticsearch Queries (ElasticQuery)
+
+`Elastic` is the mapper for `ElasticEntity`:
+
+```java
+@Part
+private Elastic elastic;
+```
+
+**Select:**
+```java
+ElasticQuery<EventLog> query = elastic.select(EventLog.class)
+                                      .eq(EventLog.EVENT_TYPE, "login")
+                                      .orderDesc(EventLog.TIMESTAMP)
+                                      .limit(100);
+
+List<EventLog> events = query.queryList();
+```
+
+**Find by ID:**
+```java
+Optional<EventLog> event = elastic.find(EventLog.class, eventId);
+```
+
+Elastic queries also support full-text search and aggregations, but the basic
+filter/sort/limit API is the same as OMA and Mango.
+
+## Common Query Methods
+
+All three query types share these methods from the `Query` base class:
+
+| Method | Description |
+|--------|-------------|
+| `eq(Mapping, value)` | Equals filter |
+| `ne(Mapping, value)` | Not-equals filter |
+| `gt(Mapping, value)` | Greater than |
+| `gte(Mapping, value)` | Greater than or equal |
+| `lt(Mapping, value)` | Less than |
+| `lte(Mapping, value)` | Less than or equal |
+| `orderAsc(Mapping)` | Sort ascending |
+| `orderDesc(Mapping)` | Sort descending |
+| `limit(int)` | Maximum results |
+| `skip(int)` | Skip n results |
+| `queryList()` | Return all matching as list |
+| `queryFirst()` | Return first match as Optional |
+| `count()` | Return count of matches |
+| `exists()` | Return true if any match exists |
+| `iterateAll(Consumer)` | Stream all matches through a consumer |
+| `delete()` | Delete all matching entities |
+
+## Filter Factories
+
+Each mapper provides a `FILTERS` factory for complex constraints:
+
+```java
+oma.select(Product.class)
+   .where(OMA.FILTERS.or(
+       OMA.FILTERS.eq(Product.CATEGORY, "electronics"),
+       OMA.FILTERS.eq(Product.CATEGORY, "appliances")
+   ))
+   .queryList();
+```
+
+Mango and Elastic have equivalent `FILTERS` factories with the same API.
+
+## Querying Composite Fields
+
+Use `Mapping.inner()` to query fields inside composites:
+
+```java
+oma.select(Customer.class)
+   .eq(Customer.PERSON.inner(PersonData.LASTNAME), "Smith")
+   .queryList();
+```
+
+## Common Mistakes
+
+1. **Calling queryList() on unbounded queries** — Always set a `limit()` or use
+   `iterateAll()` for large result sets. An unbounded `queryList()` loads
+   everything into memory.
+
+2. **Using raw strings instead of Mapping constants** — Always use `Mapping.named()`
+   constants. Raw strings bypass compile-time safety and break on refactoring.
+
+3. **Mixing mapper types** — Use `oma` for `SQLEntity`, `mango` for `MongoEntity`,
+   and `elastic` for `ElasticEntity`. Each entity class is bound to exactly one
+   mapper.
+
+4. **Ignoring iterateAll cancellation** — `iterateAll()` respects `TaskContext`
+   cancellation. Long-running iterations should check `TaskContext.get().isActive()`
+   or will be automatically stopped when the task is cancelled.

package/dist/resources/db/refs.md

@@ -0,0 +1,135 @@
+# Entity References
+
+Entity references model relationships between entities in sirius-db. Instead of
+storing a raw foreign key, references are wrapped in typed ref objects that provide
+lazy loading, delete behavior, and type safety.
+
+## BaseEntityRef<I, E> — Common Interface
+
+All reference types extend `BaseEntityRef<I, E>` (in `sirius.db.mixing.types`),
+where `I` is the ID type and `E` is the entity type. It stores the referenced
+entity's ID and lazily loads the full entity on demand.
+
+Key methods on any ref:
+- `getId()` — returns the stored ID (without loading the entity)
+- `getValue()` — loads and returns the referenced entity (cached after first load)
+- `getValueIfPresent()` — returns the entity only if already loaded
+- `setId(I)` — sets the reference by ID
+- `setValue(E)` — sets the reference by entity instance
+- `isEmpty()` / `isFilled()` — checks whether the reference is set
+- `is(E)` — checks if the ref points to the given entity
+- `hasWriteOnceSemantics()` — whether the ref is immutable after first save
+
+## OnDelete Behaviors
+
+The `OnDelete` enum defines what happens when the referenced entity is deleted:
+
+- `CASCADE` — the entity holding the reference is also deleted
+- `SET_NULL` — the reference field is set to null
+- `REJECT` — the delete is rejected (throws an exception)
+- `IGNORE` — no action is taken; the reference may become dangling
+
+## SQLEntityRef<E>
+
+For SQL entities, use `SQLEntityRef<E>`. The ID type is `Long`.
+
+```java
+public class OrderItem extends SQLTenantAware {
+
+    public static final Mapping ORDER = Mapping.named("order");
+    private final SQLEntityRef<Order> order =
+            SQLEntityRef.on(Order.class, BaseEntityRef.OnDelete.CASCADE);
+
+    public static final Mapping PRODUCT = Mapping.named("product");
+    private final SQLEntityRef<Product> product =
+            SQLEntityRef.on(Product.class, BaseEntityRef.OnDelete.REJECT);
+
+    // getters...
+    public SQLEntityRef<Order> getOrder() { return order; }
+    public SQLEntityRef<Product> getProduct() { return product; }
+}
+```
+
+### on() vs writeOnceOn()
+
+- `SQLEntityRef.on(Class, OnDelete)` — creates a **mutable** reference. The value
+  can be changed at any time.
+- `SQLEntityRef.writeOnceOn(Class, OnDelete)` — creates an **immutable** reference.
+  The value can only be set when the entity is new. Any attempt to change it after
+  the first save throws an exception.
+
+Use `writeOnceOn` for structural relationships that must never change, like
+"which tenant owns this record":
+
+```java
+private final SQLEntityRef<SQLTenant> tenant =
+        SQLEntityRef.writeOnceOn(SQLTenant.class, BaseEntityRef.OnDelete.CASCADE);
+```
+
+### Weak References
+
+SQL refs can be made "weak" to skip foreign key constraint creation in the database.
+This improves write performance but means the database will not enforce referential
+integrity:
+
+```java
+private final SQLEntityRef<AuditLog> lastAudit =
+        SQLEntityRef.on(AuditLog.class, BaseEntityRef.OnDelete.IGNORE).weak();
+```
+
+## MongoRef<E>
+
+For MongoDB entities, use `MongoRef<E>`. The ID type is `String`.
+
+```java
+public class MongoOrderItem extends MongoTenantAware {
+
+    public static final Mapping ORDER = Mapping.named("order");
+    private final MongoRef<MongoOrder> order =
+            MongoRef.on(MongoOrder.class, BaseEntityRef.OnDelete.CASCADE);
+
+    public static final Mapping PRODUCT = Mapping.named("product");
+    private final MongoRef<MongoProduct> product =
+            MongoRef.on(MongoProduct.class, BaseEntityRef.OnDelete.REJECT);
+
+    // getters...
+}
+```
+
+`MongoRef` also supports `writeOnceOn()` with the same semantics as `SQLEntityRef`.
+
+## Querying by Reference
+
+To filter by a reference field, pass the referenced entity or its ID:
+
+```java
+// By entity
+oma.select(OrderItem.class)
+   .eq(OrderItem.ORDER, order)
+   .queryList();
+
+// By ID
+oma.select(OrderItem.class)
+   .eq(OrderItem.ORDER, orderId)
+   .queryList();
+```
+
+## Common Mistakes
+
+1. **Using the wrong ref type** — `SQLEntityRef` is for `SQLEntity` subclasses;
+   `MongoRef` is for `MongoEntity` subclasses. Mixing them causes startup errors.
+
+2. **Forgetting OnDelete** — Always choose an explicit `OnDelete` behavior.
+   `IGNORE` is rarely correct; it leaves dangling references. Prefer `CASCADE`
+   for owned children and `REJECT` for required dependencies.
+
+3. **Mutating a writeOnce ref** — Attempting to change a `writeOnceOn` reference
+   after the entity has been persisted throws an exception. This is intentional;
+   restructure your logic if you need to change the relationship.
+
+4. **Not declaring refs as final** — Reference fields should be `final`. The
+   framework mutates the ref's internal state (ID, cached value) but the ref
+   object itself must not be replaced.
+
+5. **Calling getValue() in loops** — Each `getValue()` call may trigger a database
+   query. In loops, use batch loading or pre-fetch the related entities.

package/dist/resources/index.d.ts

@@ -0,0 +1,27 @@
+import { ResourceDefinition } from "./loader.js";
+type LayerFilter = string;
+/**
+ * Registry of all Sirius framework resource documents.
+ *
+ * Resources are markdown files organized by layer (kernel, web, db, biz).
+ * The registry loads all resources at construction time and provides
+ * methods for querying by layer or URI.
+ */
+export declare class ResourceRegistry {
+    private resources;
+    private byUri;
+    constructor();
+    /**
+     * Returns all resources whose layer is included in the given list.
+     */
+    getResourcesForLayers(layers: LayerFilter[]): ResourceDefinition[];
+    /**
+     * Returns a single resource by its URI, or undefined if not found.
+     */
+    getResource(uri: string): ResourceDefinition | undefined;
+    /**
+     * Returns all registered resources.
+     */
+    getAllResources(): ResourceDefinition[];
+}
+export {};

package/dist/resources/index.js

@@ -0,0 +1,68 @@
+import { loadResource } from "./loader.js";
+/**
+ * Registry of all Sirius framework resource documents.
+ *
+ * Resources are markdown files organized by layer (kernel, web, db, biz).
+ * The registry loads all resources at construction time and provides
+ * methods for querying by layer or URI.
+ */
+export class ResourceRegistry {
+    resources;
+    byUri;
+    constructor() {
+        this.resources = [
+            // Kernel (5)
+            loadResource("kernel", "di", "Dependency injection patterns: @Part, @Parts, @Register, @ConfigValue"),
+            loadResource("kernel", "lifecycle", "Lifecycle interfaces: Startable, Stoppable, Killable"),
+            loadResource("kernel", "async", "Async primitives: Tasks, CallContext, Promise, DelayLine"),
+            loadResource("kernel", "config", "Configuration system: HOCON, file precedence, framework flags"),
+            loadResource("kernel", "commons", "Common utilities: NLS, Strings, Value, Amount, Explain"),
+            // Web (3)
+            loadResource("web", "controllers", "Web controllers: routing, request handling, response rendering"),
+            loadResource("web", "services", "Web services: JSON APIs, ServiceCall, structured endpoints"),
+            loadResource("web", "templates", "Pasta/Tagliatelle template engine: syntax, tags, extensions"),
+            // DB (5)
+            loadResource("db", "entities", "Entity definitions: SQLEntity, MongoEntity, ElasticEntity"),
+            loadResource("db", "composites", "Composite pattern: reusable embedded data structures"),
+            loadResource("db", "refs", "References and foreign keys: EntityRef, BaseEntityRef"),
+            loadResource("db", "queries", "Query API: SmartQuery, filters, pagination, aggregation"),
+            loadResource("db", "mixing", "Mixing ORM: Mixins, annotations, schema management"),
+            // Biz (11)
+            loadResource("biz", "entity-triple", "Entity triple pattern: interface + SQL + Mongo implementations"),
+            loadResource("biz", "biz-controller", "BizController base class: tenant-aware controllers"),
+            loadResource("biz", "jobs", "Jobs framework: background job definitions, factories, parameters"),
+            loadResource("biz", "processes", "Process monitoring: logs, counters, state tracking"),
+            loadResource("biz", "importer", "Data import framework: ImportHandler, EntityImportHandler"),
+            loadResource("biz", "tenants", "Multi-tenant management: Tenant, UserAccount, permissions"),
+            loadResource("biz", "storage", "Object storage: Layer1 (physical), Layer2 (metadata), Layer3 (VFS)"),
+            loadResource("biz", "analytics", "Analytics: metrics, events, Clickhouse integration"),
+            loadResource("biz", "codelists", "Code lists: lookup tables, managed enumerations"),
+            loadResource("biz", "isenguard", "Isenguard: rate limiting, firewall, IP blocking"),
+            loadResource("biz", "testing", "Testing patterns: SiriusExtension, test entities, scenarios"),
+        ];
+        this.byUri = new Map();
+        for (const resource of this.resources) {
+            this.byUri.set(resource.uri, resource);
+        }
+    }
+    /**
+     * Returns all resources whose layer is included in the given list.
+     */
+    getResourcesForLayers(layers) {
+        const layerSet = new Set(layers.map((l) => l.toLowerCase()));
+        return this.resources.filter((r) => layerSet.has(r.layer));
+    }
+    /**
+     * Returns a single resource by its URI, or undefined if not found.
+     */
+    getResource(uri) {
+        return this.byUri.get(uri);
+    }
+    /**
+     * Returns all registered resources.
+     */
+    getAllResources() {
+        return [...this.resources];
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAI/D;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,CAAuB;IAChC,KAAK,CAAkC;IAE/C;QACE,IAAI,CAAC,SAAS,GAAG;YACf,aAAa;YACb,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,uEAAuE,CAAC;YACrG,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,sDAAsD,CAAC;YAC3F,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,0DAA0D,CAAC;YAC3F,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,+DAA+D,CAAC;YACjG,YAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,wDAAwD,CAAC;YAE3F,UAAU;YACV,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,gEAAgE,CAAC;YACpG,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,4DAA4D,CAAC;YAC7F,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,6DAA6D,CAAC;YAE/F,SAAS;YACT,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,2DAA2D,CAAC;YAC3F,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,sDAAsD,CAAC;YACxF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,uDAAuD,CAAC;YACnF,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,yDAAyD,CAAC;YACxF,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,oDAAoD,CAAC;YAElF,WAAW;YACX,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,gEAAgE,CAAC;YACtG,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,oDAAoD,CAAC;YAC3F,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,mEAAmE,CAAC;YAChG,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,oDAAoD,CAAC;YACtF,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,2DAA2D,CAAC;YAC5F,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,2DAA2D,CAAC;YAC3F,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,oEAAoE,CAAC;YACpG,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,oDAAoD,CAAC;YACtF,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,iDAAiD,CAAC;YACnF,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,iDAAiD,CAAC;YACnF,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,6DAA6D,CAAC;SAC9F,CAAC;QAEF,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,qBAAqB,CAAC,MAAqB;QACzC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/resources/kernel/async.md

@@ -0,0 +1,189 @@
+# Async and Concurrency
+
+Sirius-kernel provides its own concurrency primitives built around managed thread
+pools, context propagation, and a promise/future model.
+
+## Tasks Service
+
+`Tasks` is the central service for running background work. It manages named
+executor pools and ensures proper context propagation.
+
+```java
+@Part
+private Tasks tasks;
+
+// Run in the default executor
+tasks.defaultExecutor().start(() -> {
+    // Background work — CallContext is automatically transferred
+});
+
+// Run in a named executor
+tasks.executor("my-pool").start(() -> {
+    // Runs in a pool configured under "async.executor.my-pool"
+});
+```
+
+### Executor Configuration
+
+Executors are configured in HOCON:
+
+```hocon
+async.executor.my-pool {
+    poolSize = 4
+    maxSize = 16
+    queueLength = 100
+}
+```
+
+- `poolSize` — Core thread count.
+- `maxSize` — Maximum thread count under load.
+- `queueLength` — Work queue capacity. Tasks beyond this are rejected.
+
+### Periodic Tasks
+
+For recurring work, use `EveryMinute`, `EveryTenMinutes`, `EveryHour`, or
+`EveryDay` by implementing the interface and registering:
+
+```java
+@Register(classes = {CleanupTask.class, EveryHour.class})
+public class CleanupTask implements EveryHour {
+
+    @Override
+    public void runTimer() throws Exception {
+        // Called every hour
+    }
+}
+```
+
+## CallContext
+
+`CallContext` is thread-local context that automatically transfers to child
+threads managed by `Tasks`. It carries:
+
+- The current **language** (for NLS translations).
+- The current **user** and **tenant** (MDC-style context).
+- A **TaskContext** for monitoring progress and cancellation.
+- **Log output** and flow tracking.
+
+```java
+// Access current context
+CallContext ctx = CallContext.getCurrent();
+
+// Get a sub-context component
+UserInfo currentUser = ctx.get(UserInfo.class);
+```
+
+When `Tasks` dispatches work to a thread pool, it captures the caller's
+`CallContext` and installs it in the worker thread. This means background
+tasks automatically inherit the user, language, and logging context.
+
+### TaskContext
+
+Within a `CallContext`, the `TaskContext` tracks the current operation and
+supports cooperative cancellation:
+
+```java
+TaskContext taskCtx = TaskContext.get();
+
+// Check if the current task should stop
+if (!taskCtx.isActive()) {
+    return;
+}
+
+// Report progress
+taskCtx.setState("Processing item %d of %d", current, total);
+```
+
+Long-running operations should periodically check `isActive()` to support
+graceful cancellation.
+
+## Promise and Future
+
+Sirius provides its own `Promise<T>` as a lightweight alternative to
+`CompletableFuture`:
+
+```java
+// Create a promise
+Promise<String> promise = new Promise<>();
+
+// Register handlers
+promise.onSuccess(value -> {
+    // Called when the promise is fulfilled
+});
+promise.onFailure(error -> {
+    // Called when the promise fails
+});
+
+// Fulfill or fail
+promise.success("result");
+// or
+promise.fail(new IOException("failed"));
+```
+
+### Blocking Wait
+
+```java
+String result = promise.await(Duration.ofSeconds(30));
+```
+
+`await()` blocks until the promise completes or the timeout expires.
+
+### Chaining
+
+```java
+Promise<Integer> length = promise.map(String::length);
+```
+
+## DelayLine
+
+`DelayLine` provides delayed execution — tasks are submitted and executed after
+a configured delay:
+
+```java
+@Part
+private DelayLine delayLine;
+
+delayLine.callDelayed("my-token", Duration.ofMinutes(5), () -> {
+    // Executed 5 minutes from now
+});
+```
+
+The token parameter is used for deduplication — submitting a new task with the
+same token cancels the previous one. This is useful for debouncing (e.g., only
+send a notification if no further events arrive within 5 minutes).
+
+## Orchestration
+
+`Orchestration` coordinates distributed background work across cluster nodes.
+It ensures that periodic tasks run on only one node in a cluster:
+
+```java
+@Register(classes = {MyDistributedTask.class, EveryHour.class})
+public class MyDistributedTask implements EveryHour {
+
+    @Part
+    private Orchestration orchestration;
+
+    @Override
+    public void runTimer() throws Exception {
+        orchestration.runInCluster("my-task", () -> {
+            // Only executes on one node
+        });
+    }
+}
+```
+
+## Best Practices
+
+1. **Always use `Tasks`** for background work — never create raw threads.
+   `Tasks` ensures context propagation and proper executor management.
+
+2. **Check `isActive()`** in long-running loops to support cancellation.
+
+3. **Use DelayLine** for debounce patterns instead of `Thread.sleep`.
+
+4. **Configure executor pools** explicitly. The default pool is shared and
+   should not be saturated with long-running tasks.
+
+5. **Name your executors** descriptively. Executor names appear in thread dumps
+   and monitoring, making debugging much easier.