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/codingapi/tx-lcn 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

• 10 active contributors
• Distributed ownership (top contributor 31% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y 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 codingapi/tx-lcn repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/codingapi/tx-lcn.

What it runs against: a local clone of codingapi/tx-lcn — 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 codingapi/tx-lcn | 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 dev6.0 exists | Catches branch renames | | 4 | Last commit ≤ 1005 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of codingapi/tx-lcn. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/codingapi/tx-lcn.git
#   cd tx-lcn
#
# 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 codingapi/tx-lcn and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "codingapi/tx-lcn(\\.git)?\\b" \\
  && ok "origin remote is codingapi/tx-lcn" \\
  || miss "origin remote is not codingapi/tx-lcn (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 dev6.0 >/dev/null 2>&1 \\
  && ok "default branch dev6.0 exists" \\
  || miss "default branch dev6.0 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 1005 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~975d)"
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/codingapi/tx-lcn"
  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).

TX-LCN is a distributed transaction coordination framework for Java microservices that uses a centralized Transaction Manager (TM) to coordinate local transactions across multiple services and databases. It handles the 2-phase commit protocol locally on each Transaction Client (TC) instance, supporting Dubbo, Spring Cloud, and Motan RPC frameworks without requiring XA or complex state machine logic. Maven monorepo: starter-txlcn-protocol and starter-txlcn-tc provide Spring Boot integration; txlcn-tm runs the central transaction manager; txlcn-tc implements the transaction client; txlcn-protocol defines message serialization; txlcn-p6spy intercepts JDBC for SQL logging. Example modules (example-protocol-a, example-protocol-b, example-tc-2) demonstrate dual-phase rollback patterns.

Java developers building microservice architectures who need ACID guarantees across service boundaries without XA overhead. Specifically: architects evaluating transaction patterns, DevOps engineers deploying multi-database applications on Dubbo/Spring Cloud/Motan, and contributors adding database adapter support or protocol enhancements.

Production-ready (version 6.0.0 released). The repo has CI/CD setup (.travis.yml, codecov integration), comprehensive documentation including a published PDF specification (LCN分布式事务框架-20200102.pdf), and structured examples. However, Chinese-primary documentation and absence of recent commit dates in provided data suggest the core is stable but community activity may be moderate.

Low-to-moderate risk: single organization maintainer (codingapi), small test coverage visibility, and heavy reliance on external services (MySQL, Redis required). The 465KB Java codebase is substantial, but the framework's success depends entirely on TM availability—TM failure cascades to all dependent transactions. Monitor the ./sql/init.sql and dependency versions closely for breaking schema changes.

Framework is feature-complete for v6.0.0. Based on file structure, active work areas include protocol message enhancements (example/MyTxCreateGroupMsg.java patterns), TC/TM communication robustness, and multi-RPC framework support. The dev6.0 branch mentioned in badges suggests incremental polish post-release.

git clone https://github.com/codingapi/tx-lcn.git && cd tx-lcn && mvn clean install. Configure MySQL and Redis per ./sql/init.sql, then: (1) start TM server, (2) configure example-tc and example-tc-2 in application.properties, (3) run both examples, (4) test via curl http://localhost:8090/save?name=123.

Daily commands: Start TM: mvn spring-boot:run -pl txlcn-tm. Start TC instances: mvn spring-boot:run -pl example-tc and mvn spring-boot:run -pl example-tc-2. Verify: curl http://localhost:8090/save?name=test123 (triggers distributed write across both TCs).

• txlcn-tm: Central transaction manager service—orchestrates commit/rollback decisions; must be always-available
• txlcn-tc: Transaction client library embedded in each microservice; handles local undo logs and phase-2 commits
• txlcn-protocol: Message serialization spec for TC↔TM communication; protocol changes break compatibility across versions
• txlcn-p6spy: JDBC event capture layer; extracts SQL for undo-log generation and rollback simulation
• [example-protocol-a and example-protocol-b](https://github.com/codingapi/tx-lcn/blob/dev6.0/example-protocol-a and example-protocol-b): Runnable dual-service examples showing 2-phase commit in action; essential for understanding framework behavior
• sql/init.sql: Required schema initialization for TM state tables and undo-log storage; omitting breaks transaction persistence

Add database support: extend txlcn-tc/src/main/java/com/codingapi/txlcn/tc with new DataSourceAdapter. Add custom RPC: implement txlcn-protocol/src/main/java/.../protocol message handlers. Add features: modify TmRunner.java (TM logic) or DemoController.java (TC test endpoints). Database schema changes go in ./sql/init.sql.

TM server must start before any TC instance (discovery/heartbeat failure silent-fails transactions). Redis configuration in application.properties is optional but recommended for distributed cache consistency. P6Spy JDBC proxy requires explicit DataSource wrapping in Spring config—standard JdbcTemplate alone won't generate undo logs. MySQL autocommit=false is enforced by framework; explicit txn boundaries required. Undo-log replay on rollback assumes SQL idempotence—non-idempotent stored procedures may fail during abort.

• 2-Phase Commit (2PC) Protocol — TX-LCN implements a variant that avoids XA's blocking by using local transaction commits + coordinated rollback; essential to understand why TM failure is critical
• Undo Log (Inverse Transaction Log) — TX-LCN captures SQL before execution and replays DELETE/UPDATE inverses on rollback; key to avoiding distributed locks
• JDBC Event Interception via Proxy — P6Spy wraps the JDBC driver to capture SQL statements before they execute; enables undo-log generation without code changes
• Saga Pattern (Choreography vs. Orchestration) — TX-LCN uses orchestration (TM decides); understanding sagas helps recognize when LCN's synchronous approach fits vs. event-driven alternatives
• Distributed Transaction Isolation Levels — TX-LCN's local-commit model trades strict serializability for availability; must understand READ_COMMITTED implications across services
• [RPC Framework Abstraction (Dubbo/Spring Cloud/Motan)](https://dubbo.apache.org/en/docs/ and https://spring.io/projects/spring-cloud) — TX-LCN bridges multiple RPC systems via txlcn-protocol; understanding RPC integration points clarifies how TM reaches TCs across framework boundaries

• seata/seata — Alternative distributed transaction framework using AT (automatic transaction) mode; comparable feature set but different coordination strategy
• dtm-labs/dtm — Sagas and 2PC orchestrator for Go/gRPC; solves same microservice transaction problem in different language ecosystem
• apache/incubator-eventmesh — EventMesh for event-driven architecture; often paired with TX-LCN for choreography-style distributed transactions
• alibaba/canal — Binlog-based change capture; complements TX-LCN's undo-log approach for cross-service event propagation
• apache/incubator-shardingsphere — Database sharding and JDBC proxy framework; TX-LCN integrates with ShardingSphere for sharded transaction consistency

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 integration tests for Dubbo framework compatibility in example-protocol modules

The repo claims compatibility with Dubbo, Spring Cloud, and Motan frameworks, but the example modules (example-protocol-a, example-protocol-b, example-tc-2) only show basic protocol demonstrations. Adding comprehensive integration tests would verify the Dubbo compatibility claim and help new contributors understand how to use LCN with Dubbo. This is critical for a distributed transaction framework where framework integration is a core feature.

• [ ] Create example-protocol-a/src/test/java/com/codingapi/example/protocol/DubboIntegrationTest.java with Dubbo consumer/provider setup
• [ ] Create example-protocol-b/src/test/java/com/codingapi/example/protocol/DubboIntegrationTest.java with corresponding Dubbo client
• [ ] Add test configuration in example-protocol-a/src/test/resources/application-dubbo-test.properties
• [ ] Document the test execution steps in a TEST_DUBBO_INTEGRATION.md file at the example/ level

Create GitHub Actions CI workflow for multi-database compatibility testing

The repo advertises 'supports various relational databases' but .travis.yml only shows Travis CI configuration. The example-tc-2 module has mapper files suggesting database interaction, but there's no visible CI workflow testing against multiple databases (MySQL, PostgreSQL, Oracle, etc.). A GitHub Actions workflow would modernize the CI/CD and explicitly validate database compatibility claims.

• [ ] Create .github/workflows/test-multi-db.yml with matrix strategy for MySQL, PostgreSQL, and H2 databases
• [ ] Add test database initialization SQL files in example-tc-2/src/test/resources/db/ for each database variant
• [ ] Configure example-tc-2/src/test/resources/application-test-{mysql,postgres,h2}.properties for each database
• [ ] Update README.md with a badge showing multi-database test status

Add comprehensive unit tests for MyTxCreateGroupMsg and protocol message handling

The message handling classes (MyTxCreateGroupMsg.java in both example-protocol-a and example-protocol-b) appear to be custom protocol message implementations, but no test files exist. Since message serialization/deserialization is critical in distributed transaction frameworks, adding focused unit tests would improve code quality and provide examples for contributors implementing custom messages.

• [ ] Create example-protocol-a/src/test/java/com/codingapi/example/protocol/message/MyTxCreateGroupMsgTest.java testing serialization, deserialization, and field validation
• [ ] Create example-protocol-b/src/test/java/com/codingapi/example/protocol/message/MyTxCreateGroupMsgTest.java with identical test scenarios
• [ ] Add test fixtures in example-protocol-a/src/test/resources/messages/ with sample message payloads
• [ ] Document the message protocol specification in example/PROTOCOL_MESSAGE_SPEC.md

• Add integration tests for PostgreSQL and Oracle in example-tc-2 (currently MySQL-only); extend sql/init.sql with dialect variants
• Document error recovery scenarios (TM crash mid-commit, network partition during phase-2) in README with sequence diagrams; currently only covered in the PDF whitepaper
• Implement health-check endpoint in txlcn-tm to expose undo-log backlog and failed transaction count; useful for monitoring dashboards

• High · Potential SQL Injection in Database Mapper — example/example-tc-2/src/main/java/com/codingapi/example/tc/db/mapper/. The codebase contains database mappers (DemoMapper, LcnSqlParseTest3Mapper) that interact with relational databases. Without visible input validation or parameterized query implementations in the provided file structure, there is risk of SQL injection attacks, especially given the framework's support for SQL parsing. Fix: Ensure all database queries use parameterized statements/prepared statements. Implement input validation and sanitization. Use ORM frameworks that handle query parameterization automatically. Review mapper XML/code for raw SQL concatenation.
• High · Distributed Transaction Framework - Insufficient Access Control Validation — example/example-tc/src/main/java/com/codingapi/example/tc/controller/DemoController.java, example/example-tc-2/src/main/java/com/codingapi/example/tc/controller/DemoController.java. The LCN distributed transaction framework manages transactions across multiple services and protocols (Dubbo, Spring Cloud, Motan). The exposed controller endpoints (DemoController in multiple modules) may lack proper authentication and authorization checks, potentially allowing unauthorized transaction manipulation. Fix: Implement role-based access control (RBAC) for all controller endpoints. Add authentication filters/interceptors. Use Spring Security or equivalent framework. Validate transaction initiators and enforce authorization checks on transaction operations.
• High · Custom Protocol Messages - Lack of Message Validation — example/example-protocol-a/src/main/java/com/codingapi/example/protocol/message/MyTxCreateGroupMsg.java, example/example-protocol-b/src/main/java/com/codingapi/example/protocol/message/MyTxCreateGroupMsg.java. Custom message classes (MyTxCreateGroupMsg) in the protocol modules lack visible input validation. These messages are used for inter-service communication in the distributed transaction framework, making them potential vectors for deserialization attacks or injection. Fix: Implement strict input validation for all message fields. Use type checking and whitelist validation. Consider signing messages with HMAC or digital signatures. Implement schema validation before deserialization. Avoid deserializing untrusted data.
• Medium · Missing Security Headers and Input Encoding — example/example-protocol-a/src/main/java/com/codingapi/example/protocol/controller/DemoController.java, example/example-tc/src/main/java/com/codingapi/example/tc/controller/DemoController.java. The web controllers serving HTTP endpoints may not include security headers (X-Frame-Options, Content-Security-Policy, X-Content-Type-Options) or proper output encoding, potentially leading to XSS vulnerabilities. Fix: Add security headers via Spring Security or filter configuration. Implement output encoding for all user-controlled data. Use OWASP ESAPI or Spring's built-in encoding mechanisms. Add Content-Security-Policy headers.
• Medium · Insecure Deserialization Risk — example/example-protocol-a/, example/example-protocol-b/, starter-txlcn-protocol dependency. The framework handles message objects and transaction states across distributed services. Without explicit serialization safeguards, there is risk of insecure deserialization attacks when processing messages from untrusted sources. Fix: Use safe serialization methods (JSON with schema validation instead of Java serialization). Implement object input stream filters. Validate object types before deserialization. Use allowlists for deserializable classes. Enable Java serialization filters globally.
• Medium · Dependency Management - Version Pinning — example/example-protocol-a/pom.xml, parent pom.xml. The pom.xml references dependency 'starter-txlcn-protocol' version 6.0.0 without explicit vulnerability checks. The parent project example-parent is also referenced without version specification in some contexts. Fix: Use Maven dependency-check plugin to scan for known vulnerabilities. Pin all transitive dependencies explicitly. Regularly update dependencies. Monitor CVE databases for framework vulnerabilities. Use OWASP Dependency-Check in CI/CD pipeline.
• Medium · Insufficient Logging and Monitoring — undefined. Critical transaction operations across distributed services lack visible comprehensive audit logging, making it difficult to detect and investigate security incidents or unauthorized Fix: undefined

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.