fix: java runtime issues 39 and 40

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve TeaQL
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. Ubuntu 22.04]
+ - Java Version: [e.g. 17.0.10]
+ - TeaQL Version: [e.g. 1.525-RELEASE]
+ - Module (if specific): [e.g. teaql-mysql]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for TeaQL
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "maven"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: maven
+      - name: Build with Maven
+        run: mvn -B install
+      - name: SpotBugs Check
+        run: mvn spotbugs:check
+      - name: OWASP Dependency Check
+        run: mvn org.owasp:dependency-check-maven:check

.gitignore

@@ -1,10 +1,46 @@
-# Ignore Gradle project-specific cache directory
-.gradle
+# Compiled class file
+*.class
 
-# Ignore Gradle build output directory
-build
-*/build
+# Log file
+*.log
+.idea
+# BlueJ files
+*.ctxt
 
-gradle
-gradlew
-gradlew.bat
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+
+# Maven
+target/
+**/target/
+
+.DS_Store
+.gradle/
+build/
+**/build/
+
+*.py
+
+# Sensitive
+.env
+*.pem
+*.key
+*.p12
+*.jks
+credentials.json
+settings.xml
+
+# Temp files
+pom.xml.versionsBackup

AGENTS.md

@@ -0,0 +1,20 @@
+# Agent Instructions
+
+This project uses CodeGraph.
+
+The CodeGraph index is generated in the parent directory of this project, not necessarily inside the project root.
+
+Before analyzing, editing, or refactoring code, first check the parent directory for the CodeGraph index and prefer CodeGraph / MCP tools over broad grep or full-file scans.
+
+Use CodeGraph especially for:
+
+1. locating symbol definitions;
+2. finding references and usages;
+3. understanding call chains and dependencies;
+4. checking impact scope before changes;
+5. identifying related tests.
+
+If CodeGraph tools are unavailable, fall back to normal file search.
+
+## Documentation References
+* For integrating new databases and `ensureSchema` logic, you MUST read and follow: [DIALECT_INTEGRATION_GUIDE.md](./DIALECT_INTEGRATION_GUIDE.md)

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Core TeaQL Java implementation
+- Providers and runtime services

CODE_OF_CONDUCT.md

@@ -0,0 +1,69 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to TeaQL
+
+First off, thank you for considering contributing to TeaQL! It's people like you that make TeaQL such a great tool.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+* Use a clear and descriptive title.
+* Describe the exact steps which reproduce the problem.
+* Provide specific examples to demonstrate the steps.
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please provide:
+* A clear and descriptive title.
+* A step-by-step description of the suggested enhancement.
+* Explain why this enhancement would be useful.
+
+### Pull Requests
+
+1. Fork the repository and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. Ensure the test suite passes.
+4. Make sure your code conforms to our coding standards.
+5. Issue that pull request!
+
+## Coding Standards & Requirements for Acceptable Contributions
+
+To ensure consistency and quality, all contributions must adhere to the following requirements:
+
+1. **Java Version**: All code must remain compatible with Java 17.
+2. **GraalVM Compatibility**: Do not use reflection APIs. This is strictly enforced by our CI pipeline and described in the native image reflection guide.
+3. **Tests**: Any new functionality MUST include corresponding tests. Existing tests must not break.
+4. **Static Analysis**: Code must pass SpotBugs without introducing new high-priority warnings.
+5. **Commit Messages**: Use clear and descriptive commit messages. We recommend [Conventional Commits](https://www.conventionalcommits.org/).
+
+## Development Setup
+
+Please refer to the `README.md` for instructions on how to build and run the project locally.

DIALECT_INTEGRATION_GUIDE.md

@@ -0,0 +1,55 @@
+# 数据库方言接入指南 (Database Dialect Integration Guide)
+
+为了保持架构的纯净性和代码的极简，接入新的数据库方言（如 PG, MySQL, Oracle 等）以及实现表结构自动同步 (`ensureSchema`) 时，**绝对禁止重写庞大的 DDL 比对逻辑**。
+
+请所有的 AI Agent 遵循以下标准实现流程：
+
+## 1. 架构核心思想
+TeaQL 的架构分为两层：
+- **`teaql-sql-portable` (便携层)**：纯净的 AST 引擎，负责所有标准 SQL 的生成、表结构差异对比、`CREATE TABLE` 和 `ALTER TABLE ... ADD COLUMN` 等通用 DDL 的生成。
+- **`teaql-data-service-sql` (JDBC 适配层)**：基于 `SqlExecutionAdapter` 实现的与数据库真实通信的通道。
+
+## 2. 如何实现 `ensureSchema` (表结构同步)
+你**不需要**去手工遍历所有列、对比类型、拼接 CREATE/ALTER 语句，这些在 `PortableSQLRepository.ensureSchema()` 中已经完美实现。
+
+在具体的数据库方言执行器（例如 `PostgresDataServiceExecutor`）中，只需执行以下 3 步：
+
+### Step 1: 遍历所有实体模型
+利用 `EntityMetaFactory` 获取当前系统中注册的所有数据模型：
+```java
+List<EntityDescriptor> descriptors = EntityMetaFactory.get().allEntityDescriptors();
+```
+
+### Step 2: 包装局部的 `TeaQLDatabase` 提供字典数据
+`PortableSQLRepository` 只需要一个底层的 `TeaQLDatabase` 接口来查询表列信息并执行 SQL。请利用 `getExecutionAdapter()` 创建一个包装类：
+```java
+TeaQLDatabase dbAdapter = new TeaQLDatabase() {
+    @Override
+    public List<Map<String, Object>> getTableColumns(String tableName) {
+        // 【核心】：在这里写该数据库专属的字典查询 SQL
+        // 例如 PostgreSQL:
+        String sql = "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = ? AND table_schema = 'public'";
+        return getExecutionAdapter().queryForList(sql, new Object[]{tableName});
+    }
+
+    @Override
+    public void execute(String sql) {
+        getExecutionAdapter().execute(sql);
+    }
+    // ... 其他 query/update 方法直接委托给 getExecutionAdapter() 即可
+};
+```
+
+### Step 3: 交给 Portable 引擎执行 DDL
+针对每个 `EntityDescriptor`，实例化一个带有该伪装 Adapter 的 PortableRepository，并调用其 `ensureSchema` 方法：
+```java
+for (EntityDescriptor descriptor : descriptors) {
+    // 实例化方言的 PortableSQLRepository（例如 PostgresPortableSQLRepository，如果没有则用基类）
+    PortableSQLRepository repository = new PortableSQLRepository(descriptor, dbAdapter, null);
+    repository.ensureSchema(ctx);
+}
+```
+
+## 3. 核心纪律
+1. **彻底解耦 Spring**：在方言模块中，严禁直接使用 `JdbcTemplate` 或任何 `org.springframework` 包。全部通过 `SqlExecutionAdapter` 委托。
+2. **职责极简**：方言层（后端层）只负责提供“查询数据字典的原生 SQL”和“JDBC 链接”，表结构的 Diff 对比和通用 DDL 必须收口在 Portable 引擎。