If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dromara/hmily shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 23+ active contributors
• Distributed ownership (top contributor 29% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dromara/hmily repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dromara/hmily.

What it runs against: a local clone of dromara/hmily — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dromara/hmily | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 693 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dromara/hmily. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dromara/hmily.git
#   cd hmily
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dromara/hmily and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dromara/hmily(\\.git)?\\b" \\
  && ok "origin remote is dromara/hmily" \\
  || miss "origin remote is not dromara/hmily (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 693 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~663d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dromara/hmily"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hmily is a financial-grade distributed transaction framework for Java that provides reliable transaction handling across multiple services using TCC (Try-Confirm-Cancel), TAC (Try-Auto-Confirm), and XA patterns. It prevents transaction suspension and enables automatic recovery of failed distributed transactions, with zero-invasive Spring Boot/Spring Namespace integration. Multi-module Maven monorepo with clear separation: hmily-annotation defines @HmilyTCC/@HmilyTAC/@HmilyXA/@HmilyXA decorators, hmily-common provides shared utilities (enums, exceptions, hooks in org.dromara.hmily.common.), and hmily-bom manages version dependencies. Module naming follows org.dromara.hmily. package structure.

Java microservices architects and backend engineers building distributed systems who need ACID-like guarantees across multiple databases without heavyweight distributed transaction coordinators. Particularly relevant for fintech platforms and high-reliability payment systems.

Production-ready with active maintenance. Version 2.1.3-SNAPSHOT indicates ongoing development, Maven Central presence shows established release cadence, CI/CD pipeline (GitHub Actions in .github/workflows/main.yml) is configured, and comprehensive test coverage exists. Project is part of the Dromara open-source organization, indicating institutional backing.

Risk is low to moderate: lightweight dependency footprint (only Lombok in annotation module), but Java-only ecosystem limits language flexibility. Project appears actively maintained with structured GitHub workflows, though snapshot version suggests some instability in current development branch. Monitor issue backlog and check commit frequency to assess resource commitment.

Currently in 2.1.3-SNAPSHOT development cycle. GitHub Actions workflow (main.yml) is configured for continuous build/test on commits. Project appears to be actively maintained with focus on annotation-driven transaction handling and common library enhancements.

git clone https://github.com/dromara/hmily.git && cd hmily && mvn clean install

Daily commands: This is a library framework, not a runnable application. To use: add dependency org.dromara:hmily-spring-boot-starter (version 2.1.3) to your Spring Boot project pom.xml, then annotate distributed transaction methods with @HmilyTCC or @HmilyTAC. Build with: mvn clean package

• hmily-annotation/src/main/java/org/dromara/hmily/annotation/HmilyTCC.java: Core TCC (Try-Confirm-Cancel) annotation that marks distributed transaction entry points
• hmily-annotation/src/main/java/org/dromara/hmily/annotation/TransTypeEnum.java: Enum defining supported transaction types (TCC, TAC, XA) used by all transaction implementations
• hmily-common/src/main/java/org/dromara/hmily/common/enums/HmilyActionEnum.java: State machine actions (TRY, CONFIRM, CANCEL) that control transaction lifecycle across all patterns
• hmily-common/src/main/java/org/dromara/hmily/common/hook/HmilyShutdownHook.java: Graceful shutdown handler ensuring pending transactions are properly finalized on JVM exit
• hmily-common/src/main/java/org/dromara/hmily/common/enums/RepositorySupportEnum.java: SPI abstraction for pluggable transaction log storage backends (MySQL, PostgreSQL, MongoDB, Redis, etc.)

For annotation enhancements: edit hmily-annotation/src/main/java/org/dromara/hmily/annotation/*.java. For shared utilities: modify hmily-common/src/main/java/org/dromara/hmily/common/{concurrent,constant,enums,exception,hook,utils}/ files. For new propagation/isolation logic: add to IsolationLevelEnum.java and PropagationEnum.java. All changes require Maven module rebuild: mvn -pl [module-name] clean install

PostgreSQL support uses PLpgSQL (visible in 12KB of PLpgSQL code), indicating native DB procedures are required for some backends—ensure target database has required functions. Transaction state serialization depends on SerializeEnum plugin selection (Kryo/Protostuff/Hessian)—mismatched serialization between nodes causes data corruption. HmilyThreadFactory uses custom thread pools—monitor thread pool exhaustion in high-concurrency scenarios. PropagationEnum.REQUIRED behavior differs from Spring TX propagation—review isolation level docs before upgrading.

• TCC (Try-Confirm-Cancel) Pattern — Hmily's primary transaction model requiring explicit confirm/cancel methods; understanding the two-phase contract is essential to using @HmilyTCC correctly
• Saga Pattern (TAC variant) — TAC (Try-Auto-Confirm) implements the Saga pattern for long-running transactions; critical for workflows spanning multiple services
• Distributed Transaction Idempotency — Hmily's recovery mechanism relies on idempotent confirm/cancel operations to safely retry failed transactions without duplication
• XA (Two-Phase Commit) — Hmily supports XA protocol for ACID compliance; requires understanding resource managers and transaction coordinators
• Event Sourcing for Transaction Logs — EventTypeEnum and transaction state persistence model use event-driven architecture to replay and recover failed transactions
• Service Provider Interface (SPI) Pattern — RepositorySupportEnum and SerializeEnum use SPI for pluggable implementations; essential for extending Hmily with custom backends
• AOP (Aspect-Oriented Programming) Interception — Hmily's zero-invasive integration works via Spring AOP intercepting @HmilyTCC/@HmilyTAC annotated methods; understanding method interception is crucial for debugging

• seata/seata — Competing distributed transaction framework from Alibaba using AT (automatic transaction) pattern; compare design philosophy and performance characteristics
• dtm-labs/dtm — Language-agnostic distributed transaction manager supporting gRPC; shows alternative approach to Hmily's Java-centric annotation model
• dromara/solon — Sibling Dromara project providing lightweight alternative to Spring Boot; Hmily integrates with this ecosystem
• Apache/ShardingSphere — Database middleware often used alongside Hmily for cross-shard distributed transactions and data sharding
• alibaba/spring-cloud-alibaba — Ecosystem integrating Nacos service discovery with transaction frameworks; shows how Hmily fits into larger microservices stack

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for hmily-common utility classes

The hmily-common module has many utility classes (StringUtils, DateUtils, DbTypeUtils, NetUtils, etc.) but only StringUtilsTest.java exists. A distributed transaction framework depends heavily on utility reliability. Adding tests for utilities like IdWorkerUtils (ID generation), RepositoryPathUtils (path handling), DbTypeUtils (database type detection), and UrlUtils will improve code quality and prevent regressions in core functionality.

• [ ] Create hmily-common/src/test/java/org/dromara/hmily/common/utils/IdWorkerUtilsTest.java with tests for ID generation edge cases
• [ ] Create hmily-common/src/test/java/org/dromara/hmily/common/utils/DbTypeUtilsTest.java testing database type detection for PostgreSQL, MySQL, Oracle, H2
• [ ] Create hmily-common/src/test/java/org/dromara/hmily/common/utils/UrlUtilsTest.java with URL parsing and validation tests
• [ ] Create hmily-common/src/test/java/org/dromara/hmily/common/utils/RepositoryPathUtilsTest.java for path construction scenarios
• [ ] Add tests to hmily-common/src/test/java/org/dromara/hmily/common/utils/StringUtilsTest.java for any missing edge cases

Add unit tests for hmily-annotation enum classes and validation

The hmily-annotation module defines critical enums (TransTypeEnum, PropagationEnum, IsolationLevelEnum, HmilyRoleEnum) that control distributed transaction behavior. Currently there are no tests for these enums. Adding tests ensures enum values are correctly defined, serialization works properly, and edge cases in transaction type/propagation logic are covered.

• [ ] Create hmily-annotation/src/test/java/org/dromara/hmily/annotation/TransTypeEnumTest.java verifying all transaction types (TCC, TAC, XA) are properly defined
• [ ] Create hmily-annotation/src/test/java/org/dromara/hmily/annotation/PropagationEnumTest.java testing transaction propagation scenarios
• [ ] Create hmily-annotation/src/test/java/org/dromara/hmily/annotation/IsolationLevelEnumTest.java validating isolation level definitions
• [ ] Create hmily-annotation/src/test/java/org/dromara/hmily/annotation/HmilyRoleEnumTest.java for provider/consumer role tests
• [ ] Add integration tests verifying annotation parsing on @Hmily, @HmilyTCC, @HmilyTAC, @HmilyXA

Add GitHub Actions workflow for multi-database integration testing

Hmily is a distributed transaction solution supporting multiple databases (MySQL, PostgreSQL, Oracle, H2). The .github/workflows/main.yml likely only runs basic compilation tests. A dedicated multi-database integration test workflow would catch database-specific issues early. This is critical for a transaction framework where database compatibility is essential.

• [ ] Create .github/workflows/database-integration-tests.yml that runs on PR/push events
• [ ] Configure the workflow to start PostgreSQL, MySQL, and H2 database services using GitHub Actions service containers
• [ ] Add matrix strategy to test against different database versions (MySQL 5.7, 8.0; PostgreSQL 12, 14, 15)
• [ ] Execute integration tests from hmily modules against each database configuration
• [ ] Add workflow status badge to README.md showing integration test results

• Add comprehensive Javadoc comments to all enums in hmily-common/src/main/java/org/dromara/hmily/common/enums/ (EventTypeEnum, ExecutorTypeEnum, HmilyActionEnum, HmilyRoleEnum, RejectedPolicyTypeEnum, RepositorySupportEnum, SerializeEnum) with usage examples
• Create integration tests for each TransTypeEnum variant (TCC, TAC, XA) in a new hmily-test module demonstrating success and rollback scenarios with mock repositories
• Document the SPI contract for RepositorySupportEnum in README.md or a new PLUGINS.md file, showing how to implement a custom repository backend for unsupported databases

The Hmily distributed transaction framework demonstrates a moderate security posture. Key concerns include potential

• Medium · Lombok Dependency Without Version Pinning — hmily-annotation/pom.xml. The hmily-annotation module depends on Lombok without an explicitly defined version in the pom.xml. This relies on the parent POM for version management, which could lead to unexpected version updates if the parent BOM is updated. Lombok processes annotations at compile-time and has had historical security concerns. Fix: Ensure the parent POM explicitly pins a recent, stable version of Lombok (e.g., 1.18.30+). Consider regularly auditing Lombok for CVEs and document the minimum required version.
• Medium · Potential Deserialization Vulnerabilities in Distributed Transaction Handling — hmily-common/src/main/java/org/dromara/hmily/common/utils/GsonUtils.java and hmily-common/src/main/java/org/dromara/hmily/common/enums/SerializeEnum.java. The codebase includes SerializeEnum and serialization utilities (GsonUtils) used in distributed transaction scenarios. Deserialization of untrusted data (transaction logs, participant state) without proper validation could lead to code execution attacks, especially if using Java serialization or unsafe JSON deserialization patterns. Fix: Implement strict deserialization whitelisting, use JSON parsing with explicit type constraints, avoid Java serialization for untrusted data, and validate all deserialized transaction objects against a schema.
• Medium · Network Communication Without Explicit TLS Configuration Visibility — hmily-common/src/main/java/org/dromara/hmily/common/utils/NetUtils.java and hmily-common/src/main/java/org/dromara/hmily/common/utils/UrlUtils.java. The NetUtils and UrlUtils classes suggest network communication between distributed transaction participants. No visible evidence of mandatory TLS/SSL enforcement or certificate validation in the provided file structure. Fix: Enforce TLS 1.2+ for all inter-service communication, implement certificate pinning, validate certificates properly, and document security requirements in configuration.
• Medium · IdWorker Implementation Exposure — hmily-common/src/main/java/org/dromara/hmily/common/utils/IdWorkerUtils.java. The IdWorkerUtils generates transaction IDs. If the ID generation algorithm is predictable or the internal state is exposed, attackers could forge transaction IDs, leading to transaction manipulation or replay attacks. Fix: Ensure IdWorker uses cryptographically secure random generation, validate ID formats strictly, implement rate limiting on transaction operations, and monitor for suspicious ID patterns.
• Low · Debug/Logging Utilities May Expose Sensitive Information — hmily-common/src/main/java/org/dromara/hmily/common/utils/LogUtil.java. The LogUtil class could potentially log sensitive transaction data, participant credentials, or state information if not carefully configured. Distributed transaction logs may contain PII or financial data. Fix: Implement log sanitization, redact sensitive fields (credentials, personal data), use appropriate log levels for sensitive operations, and secure log storage with encryption.
• Low · Missing Input Validation Framework Evidence — hmily-annotation and hmily-config modules. While AssertUtils exists, there is limited visibility into comprehensive input validation across the transaction coordination logic. User-supplied parameters in transaction annotations could be inadequately validated. Fix: Implement comprehensive input validation for all transaction configuration parameters, validate annotation attributes, and use a validation framework (Jakarta Validation) consistently across the codebase.
• Low · File Operations Without Clear Security Controls — hmily-common/src/main/java/org/dromara/hmily/common/utils/FileUtils.java and hmily-common/src/main/java/org/dromara/hmily/common/utils/RepositoryPathUtils.java. FileUtils and RepositoryPathUtils are used for transaction log storage. If file permissions or paths are not properly secured, this could expose transaction logs or allow unauthorized modifications. Fix: Ensure transaction log files are stored with restrictive permissions (600), validate all file paths to prevent directory traversal, encrypt sensitive transaction data at rest, and implement file integrity checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.