Making future events happen reliably, powered by Java 25 Virtual Threads.

LoomQ is a durable time kernel for distributed systems — scheduling, persistence, recovery, retry orchestration, and deadline handling. Embed it as a library or run it as a standalone server.

LoomQ is:

• a durable scheduling kernel for future events (called Intents)
• embeddable (loomq-core, zero HTTP/JSON deps) or standalone (loomq-server, Netty HTTP)
• extensible via SPI hooks for delivery, callbacks, and retry decisions

LoomQ is not:

• a general-purpose message queue
• a workflow engine
• a lock or lease service (those belong in layers above the kernel)

• JDK 25+
• Maven 3.9+

<dependency>
    <groupId>com.loomq</groupId>
    <artifactId>loomq-core</artifactId>
    <version>0.9.2</version>
</dependency>

git clone https://github.com/xuyuchen9/loomq.git
cd loomq
mvn clean package -DskipTests

java -jar loomq-server/target/loomq-server-0.9.2.jar

Server listens on http://localhost:7928 by default.

curl -X POST http://localhost:7928/v1/intents \
  -H "Content-Type: application/json" \
  -d '{
    "executeAt": "'$(date -u -d "+30 seconds" +%Y-%m-%dT%H:%M:%SZ)'",
    "precisionTier": "STANDARD",
    "callback": {
      "url": "http://your-server/callback",
      "method": "POST"
    }
  }'

curl http://localhost:7928/v1/intents/{intentId}

When LOOMQ_RAFT_ENABLED=true, the standalone server switches to Raft mode:

• Leader-authoritative reads AND writes — GET /v1/intents/{intentId} and POST/PATCH /v1/intents require leader
• followers return 503 with error codes 50301 (read redirect), 50302 (write redirect), 50303 (write backpressure); retryable=true and leader id in details when known
• RaftWriteCoordinator provides bounded backpressure, request deduplication, and optimistic concurrency via X-LoomQ-Expected-Revision header
• /health and /metrics expose Raft signals: role, leader id, term, commit index, commit lag, replication lag, peer reachability, and leader read/write acceptance status
• /health/deep adds tier backpressure data on top of the Raft view
• /health/ready returns 503 with Raft reason codes when not in ready state

# Build the CLI
mvn package -pl loomq-cli -am -DskipTests

# Run (defaults to http://localhost:7928, override with LOOMQ_URL env var)
java -jar loomq-cli/target/loomq-cli-0.9.2.jar

# Or set a custom server URL
$env:LOOMQ_URL="http://localhost:7928"; java -jar loomq-cli/target/loomq-cli-0.9.2.jar

Interactive commands: schedule, get, list, chronoscope, timeline, dead-letters, revive, health, follow, help, exit.

Test Environment: JDK 25.0.2, Windows 11, 22 cores, 8GB heap, localhost, Netty mock server (tiered HTTP delays).

System QPS: 3,504.5 | Pipeline: scheduler p50=3,595ms p95=19,987ms | delivery p50=12ms p95=13ms

E2E latency = executeAt → webhook received. The dominant factor is scheduler precision (executeAt → dequeue), while delivery (dequeue → webhook received) is consistently ~12–14ms across tiers.

Key Insight: CohortManager consolidates 100,000 per-intent VT sleeps into 5 daemon wake events. Combined with batch delivery, the scheduler achieves both scheduling efficiency and HTTP economy.

The low borrow rate in steady-state tests reflects sufficient per-tier capacity under uniform load. Arrow borrowing is designed for burst scenarios — when a tier's slots are saturated, consumers transparently borrow from lower-priority idle tiers with AdapTBF's 50% lend cap preventing starvation.

Test: 10,000 intents with 2h delay, DURABLE WAL, measured before/after swap-out.

Key Insight: For 1 million long-delay intents, cold swap reduces heap from ~450 MB to ~130 MB. The swap-in daemon reloads intents from WAL 60s before executeAt with sub-millisecond latency since WAL positions are known at swap-out time.

Selection Guide:

• Sub-50ms deadlines: ULTRA or FAST
• Order timeouts and scheduled notifications: STANDARD (best balance of throughput and latency)
• Massive batch scheduling (>1h delay): ECONOMY (highest resource efficiency)

import com.loomq.LoomqEngine;
import com.loomq.domain.intent.Intent;
import com.loomq.domain.intent.PrecisionTier;
import com.loomq.spi.DeliveryHandler;
import com.loomq.spi.DeliveryHandler.DeliveryResult;

LoomqEngine engine = LoomqEngine.builder()
    .walDir(Path.of("./data"))
    .defaultTier(PrecisionTier.FAST)
    .intentStore(new RocksDBIntentStore(Path.of("./db")))  // optional: pluggable storage
    .deliveryHandler(intent -> {
        System.out.println("Intent fired: " + intent.getIntentId());
        return DeliveryResult.SUCCESS;
    })
    .build();

engine.registerObserver(new IntentObserver() {
    @Override public void onDelivered(Intent i, DeliveryResult r) {
        System.out.println("Delivered: " + i.getIntentId());
    }
    // ... other callbacks
});

engine.start();

// Schedule an intent 5 seconds from now
Intent intent = new Intent();
intent.setExecuteAt(Instant.now().plusSeconds(5));
intent.setPrecisionTier(PrecisionTier.STANDARD);
engine.createIntent(intent, AckMode.ASYNC);

// ... when done:
engine.close();

Use cases for embedded mode: single-node apps, integration tests, resource-constrained environments, custom shells on top of LoomQ core.

loomq-cli (interactive temporal explorer shell)
    └── HTTP client → loomq-server REST API

loomq-server (Netty HTTP + JSON + security)
    ├── IntentHandler        — REST API routing (RadixTree) + error recovery advisor
    ├── NettyHttpServer      — epoll + pooled allocator + semaphore backpressure
    ├── SecurityConfig       — token-based authentication
    └── loomq-channel        — pluggable delivery channels
        ├── loomq-channel-http  — HTTP webhook delivery + batch delivery
        └── loomq-channel-grpc  — gRPC streaming delivery (AUTO_ACK / MANUAL_ACK)

loomq-core (embeddable kernel, zero HTTP/JSON deps)
    ├── LoomqEngine           — builder-pattern entry point
    ├── PrecisionScheduler    — time-wheel buckets, per-tier scan + batch consumers
    │   ├── CohortManager     — CSA-style batched wakeup (replaces per-intent VT sleep)
    │   ├── BucketGroupManager — per-tier time-bucket storage
    │   ├── ResizableSemaphore — runtime-adjustable concurrency (extends Semaphore)
    │   ├── ChronoscopeSnapshot — scheduler internal state X-ray for diagnostics
    │   └── TierAdvisor       — SLO → tier recommendation with safety margin
    ├── ColdIntentSwapper     — long-delay intent memory swap-out/in; 72.5% heap reduction
    ├── HealthNarrator        — narrative health with vitals and anomaly detection
    ├── TimelineService       — temporal forecast (upcoming wakes, scheduler preview)
    ├── WalReplayService      — WAL time-travel debugging (intent lifecycle reconstruction)
    ├── IntentStore (interface) — pluggable storage (ConcurrentIntentStore / RocksDBIntentStore)
    ├── SimpleWalWriter       — segmented WAL with FFM API, auto-truncation
    ├── RecoveryPipeline      — snapshot + WAL replay on restart
    └── SPI interfaces        — DeliveryHandler, CallbackHandler, IntentObserver, WalAccessor, RedeliveryDecider

Batch Consumers (fire-and-forget): Each tier runs N virtual-thread consumers. A consumer acquires a permit (own tier or borrowed), polls the dispatch queue, and calls deliveryHandler.deliverAsync(). The permit is released in the async callback — consumer threads never block on HTTP.

Cohort Wakeup (CSA-inspired): Intents with delay > precision window are grouped by cohort key. A single daemon thread wakes each cohort at its due time, flushing all intents into the bucket. This replaces per-intent virtual-thread sleep — one thread handles thousands of intents.

Arrow Borrowing (AdapTBF-bounded): When a tier's own semaphore is exhausted, consumers attempt tryAcquire(100ms) on each lower-priority tier. Up to 50% of a tier's slots can be lent. Borrowed permits are returned on the lender's semaphore, with borrowedCount tracking.

{
  "executeAt": "2026-05-01T10:30:00Z",
  "deadline": "2026-05-01T11:00:00Z",
  "precisionTier": "STANDARD",
  "ackLevel": "DURABLE",
  "idempotencyKey": "req-abc-123",
  "callback": {
    "url": "https://example.com/webhook",
    "method": "POST",
    "headers": {"X-Request-Id": "123"}
  },
  "redelivery": {
    "maxAttempts": 5,
    "backoff": "exponential",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000
  },
  "tags": {"tenant": "demo"}
}

Required: executeAt | Optional: intentId, deadline, expiredAction, precisionTier, shardKey, ackLevel, callback, redelivery, idempotencyKey, tags

All error responses include a structured ErrorResponse body with errorCode, message, retryable flag, and optional recoveryHint providing actionable next steps.

DeliveryResult enum: SUCCESS, RETRY, DEAD_LETTER, EXPIRED

Configuration is loaded from (highest to lowest priority):

1. JVM system properties (-Dloomq.xxx)
2. External ./config/application.yml
3. Classpath application.yml
4. @DefaultValue annotations

Key config groups: server.*, netty.*, wal.*, scheduler.*, dispatcher.*, retry.*, recovery.*

See Configuration Reference for the complete key list.

• LoomQ CLI — interactive terminal for scheduling, querying, and troubleshooting
• /v1/admin/chronoscope — scheduler X-ray snapshot (per-tier state, semaphore, borrow stats)
• /v1/admin/timeline — temporal forecast (cohort wakes, scheduler activity preview)
• /health/deep — deep health with tier backpressure data
• /v1/admin/dead-letters — dead letter queue inspection and triage

# Build and run single node
make docker-build && make docker-run

# Single-node + monitoring stack (Prometheus + Grafana)
docker-compose --profile full up -d

make build          # Full build with tests
make build-fast     # Build without tests
make format         # Apply Spotless formatting
make check-format   # Verify Spotless formatting
make test           # Run default test suite
make run            # Build and start server
make docker-build   # Build Docker image

• Cohort-based batched wakeup (CSA-inspired)
• Arrow cross-tier slot borrowing + AdapTBF constraints
• ResizableSemaphore (runtime concurrency adjustment)
• Cold swap: long-delay intent memory optimization (72.5% heap reduction)
• Segmented WAL with auto-truncation
• Pluggable storage engine: IntentStore interface + ConcurrentIntentStore + RocksDBIntentStore
• IntentObserver SPI for lifecycle hooks
• WalAccessor SPI for WAL read/truncation
• Raft leader election, log replication, snapshot catch-up, leader-authoritative reads/writes
• Raft write coordination: bounded backpressure, request deduplication, optimistic concurrency
• Observable backpressure (no silent drops)
• Expiry index: O(log n) expired intent scanning
• LoomQ CLI: interactive temporal explorer shell with 10+ commands
• HealthNarrator: narrative health with vitals and anomaly detection
• ErrorRecoveryAdvisor: actionable recovery hints per error code
• TimelineService: temporal forecast and cohort wake preview
• TierAdvisor: SLO → tier recommendation with safety margin
• WalReplayService: WAL time-travel debugging
• Dead letter revival: revive dead-lettered intents with optional reschedule
• Intent listing: GET /v1/intents with status filter
• Token authentication: X-LoomQ-Token header with constant-time comparison
• ChronoscopeSnapshot: scheduler internal state X-ray for diagnostics
• Benchmark suite: WAL throughput, storage comparison, observer overhead

• Dynamic Raft membership management
• Kubernetes operator
• Web-based management console

• Release Checklist
• Benchmark Guide
• Configuration Reference
• Architecture Details
• Core Model

Issues and pull requests are welcome. See CONTRIBUTING.md for guidelines.

Copyright 2026 LoomQ Authors

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.