chore(release): 0.2.0-alpha

CHANGELOG.md

@@ -13,6 +13,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [0.2.0-alpha] - 2026-05-09
+
+Second public alpha focused on Java-native structured extraction hardening and
+release safety.
+
+### Added
+
+- Java-native schema generation for records and simple POJOs, including nested
+  objects, lists, maps, enums, dates, numbers, Jackson property annotations, and
+  fail-fast rejection for raw `Object` / unbounded shapes.
+- Typed extraction contract tests proving Java records are schema-validated
+  before deserialization, then retried on repairable provider output.
+- Internal mapper support for `Optional<T>` so absent and explicit `null`
+  values map consistently to `Optional.empty()`.
+
+### Changed
+
+- `Optional<T>` now has precise schema semantics: it is omitted from
+  `required`, and only Optional fields include `null` in their generated type.
+- Non-Optional reference fields are strict: explicit JSON `null` is rejected by
+  local schema validation before typed object mapping.
+- Custom dotted field constraints now traverse Optional intermediate values
+  safely, so caller-owned validation works for optional nested objects.
+- CI now requires Spotless, Checkstyle, full recorded verification, integration
+  tests, and Jacoco coverage gates before merge; release tags verify before
+  deploying to Maven Central.
+
+### Fixed
+
+- Fixed Java typed extraction paths where Optional fields could validate at the
+  schema layer but fail during runtime object mapping.
+- Fixed overly permissive non-Optional object schemas that previously accepted
+  `null`.
+
 ## [0.1.0-alpha] - 2026-05-09
 
 First public alpha. The audit primitives the Java enterprise stack has been
@@ -59,5 +93,6 @@ missing — every LLM-extracted field carries a verifiable evidence chain
   failures via `dev.failsafe:failsafe`; per-call retry count carried on
   `Provenance`.
 
-[Unreleased]: https://github.com/doctruthhq/DocTruth/compare/v0.1.0-alpha...HEAD
+[Unreleased]: https://github.com/doctruthhq/DocTruth/compare/v0.2.0-alpha...HEAD
+[0.2.0-alpha]: https://github.com/doctruthhq/DocTruth/compare/v0.1.0-alpha...v0.2.0-alpha
 [0.1.0-alpha]: https://github.com/doctruthhq/DocTruth/releases/tag/v0.1.0-alpha

README.es.md

@@ -29,7 +29,7 @@ No es un framework de agentes, un framework de chains, un wrapper de bases vecto
 Requiere Java 25+. Verifica Maven Central:
 
 ```bash
-mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
+mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha
 ```
 
 Usar en un proyecto Maven:
@@ -38,11 +38,11 @@ Usar en un proyecto Maven:
 <dependency>
     <groupId>ai.doctruth</groupId>
     <artifactId>doctruth-java</artifactId>
-    <version>0.1.0-alpha</version>
+    <version>0.2.0-alpha</version>
 </dependency>
 ```
 
-Gradle usa la misma coordenada: `ai.doctruth:doctruth-java:0.1.0-alpha`.
+Gradle usa la misma coordenada: `ai.doctruth:doctruth-java:0.2.0-alpha`.
 
 Actualizar a la última release:
 
@@ -110,7 +110,7 @@ DocTruth soporta exportaciones comunes de Pydantic v2 JSON Schema, incluyendo `$
 Herramienta de migración en build-time:
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar \
+java -jar target/doctruth-java-0.2.0-alpha.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   --out schemas/resume.schema.json \
   --check
@@ -134,8 +134,8 @@ Los clientes usan `java.net.http.HttpClient` del JDK; no hay SDKs de proveedores
 ## CLI
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf
-java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
+java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf
+java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
 ```
 
 ## Documentación
@@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo
 
 ## Estado
 
-`0.1.0-alpha` es una alpha pública temprana. La API es usable, está probada y se publica para recibir feedback, pero puede cambiar antes de `1.0`.
+`0.2.0-alpha` es una alpha pública temprana. La API es usable, está probada y se publica para recibir feedback, pero puede cambiar antes de `1.0`.
 
-Baseline actual: 628 unit tests y 16 integration tests pasando, con 2 smoke tests externos omitidos, coverage gates en 90% line / 80% branch, jar único de aproximadamente 202 KB.
+Baseline actual: 645 unit tests y 16 integration tests pasando, con 2 smoke tests externos omitidos, coverage gates en 90% line / 80% branch, jar único de aproximadamente 205 KB.
 
 ## Licencia
 

README.md

@@ -29,7 +29,7 @@ It is not an agent framework, chain framework, vector database wrapper, or UI. I
 Requires Java 25+. Verify Maven Central availability:
 
 ```bash
-mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
+mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha
 ```
 
 Use in a Maven project:
@@ -38,11 +38,11 @@ Use in a Maven project:
 <dependency>
     <groupId>ai.doctruth</groupId>
     <artifactId>doctruth-java</artifactId>
-    <version>0.1.0-alpha</version>
+    <version>0.2.0-alpha</version>
 </dependency>
 ```
 
-Gradle uses the same coordinate: `ai.doctruth:doctruth-java:0.1.0-alpha`.
+Gradle uses the same coordinate: `ai.doctruth:doctruth-java:0.2.0-alpha`.
 
 Upgrade to the latest release:
 
@@ -123,7 +123,7 @@ DocTruth supports common Pydantic v2 JSON Schema exports, including local `$defs
 Build-time helper:
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar \
+java -jar target/doctruth-java-0.2.0-alpha.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   --out schemas/resume.schema.json \
   --check
@@ -147,8 +147,8 @@ Provider clients use JDK `java.net.http.HttpClient`; no vendor SDKs are on the c
 ## CLI
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf
-java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
+java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf
+java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
 ```
 
 ## Documentation
@@ -163,9 +163,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo
 
 ## Status
 
-`0.1.0-alpha` is an early public alpha. The API is usable, tested, and published for feedback, but may still change before `1.0`.
+`0.2.0-alpha` is an early public alpha. The API is usable, tested, and published for feedback, but may still change before `1.0`.
 
-Current verification baseline: 628 unit tests and 16 integration tests passing, with 2 external smoke tests skipped, coverage gates at 90% line / 80% branch, single jar about 202 KB.
+Current verification baseline: 645 unit tests and 16 integration tests passing, with 2 external smoke tests skipped, coverage gates at 90% line / 80% branch, single jar about 205 KB.
 
 ## License
 

README.zh-CN.md

@@ -29,7 +29,7 @@ DocTruth 主要回答一个问题：
 需要 Java 25+。验证 Maven Central 可用：
 
 ```bash
-mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
+mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha
 ```
 
 在 Maven 项目中使用：
@@ -38,11 +38,11 @@ mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
 <dependency>
     <groupId>ai.doctruth</groupId>
     <artifactId>doctruth-java</artifactId>
-    <version>0.1.0-alpha</version>
+    <version>0.2.0-alpha</version>
 </dependency>
 ```
 
-Gradle 使用同一个坐标：`ai.doctruth:doctruth-java:0.1.0-alpha`。
+Gradle 使用同一个坐标：`ai.doctruth:doctruth-java:0.2.0-alpha`。
 
 升级到最新 release：
 
@@ -110,7 +110,7 @@ DocTruth 支持常见 Pydantic v2 JSON Schema 输出，包括本地 `$defs` / `$
 构建期迁移工具：
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar \
+java -jar target/doctruth-java-0.2.0-alpha.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   --out schemas/resume.schema.json \
   --check
@@ -134,8 +134,8 @@ Provider client 使用 JDK `java.net.http.HttpClient`，不引入 vendor SDK。
 ## CLI
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf
-java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
+java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf
+java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
 ```
 
 ## 文档
@@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo
 
 ## 状态
 
-`0.1.0-alpha` 是早期公开 alpha。API 已可用、已测试、可供反馈，但在 `1.0` 前仍可能调整。
+`0.2.0-alpha` 是早期公开 alpha。API 已可用、已测试、可供反馈，但在 `1.0` 前仍可能调整。
 
-当前验证基线：628 个 unit test 和 16 个 integration test 通过，2 个外部 smoke test 跳过，覆盖率门槛为 90% line / 80% branch，单 jar 约 202 KB。
+当前验证基线：645 个 unit test 和 16 个 integration test 通过，2 个外部 smoke test 跳过，覆盖率门槛为 90% line / 80% branch，单 jar 约 205 KB。
 
 ## License
 

README.zh-TW.md

@@ -29,7 +29,7 @@ DocTruth 主要回答一個問題：
 需要 Java 25+。驗證 Maven Central 可用：
 
 ```bash
-mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
+mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.2.0-alpha
 ```
 
 在 Maven 專案中使用：
@@ -38,11 +38,11 @@ mvn dependency:get -Dartifact=ai.doctruth:doctruth-java:0.1.0-alpha
 <dependency>
     <groupId>ai.doctruth</groupId>
     <artifactId>doctruth-java</artifactId>
-    <version>0.1.0-alpha</version>
+    <version>0.2.0-alpha</version>
 </dependency>
 ```
 
-Gradle 使用同一個座標：`ai.doctruth:doctruth-java:0.1.0-alpha`。
+Gradle 使用同一個座標：`ai.doctruth:doctruth-java:0.2.0-alpha`。
 
 升級到最新 release：
 
@@ -110,7 +110,7 @@ DocTruth 支援常見 Pydantic v2 JSON Schema 輸出，包括本地 `$defs` / `$
 建置期遷移工具：
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar \
+java -jar target/doctruth-java-0.2.0-alpha.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   --out schemas/resume.schema.json \
   --check
@@ -134,8 +134,8 @@ Provider client 使用 JDK `java.net.http.HttpClient`，不引入 vendor SDK。
 ## CLI
 
 ```bash
-java -jar target/doctruth-java-0.1.0-alpha.jar parse contract.pdf
-java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
+java -jar target/doctruth-java-0.2.0-alpha.jar parse contract.pdf
+java -jar target/doctruth-java-0.2.0-alpha.jar migrate pydantic myapp.schemas:Model --out schema.json --check
 ```
 
 ## 文件
@@ -150,9 +150,9 @@ java -jar target/doctruth-java-0.1.0-alpha.jar migrate pydantic myapp.schemas:Mo
 
 ## 狀態
 
-`0.1.0-alpha` 是早期公開 alpha。API 已可用、已測試、可供回饋，但在 `1.0` 前仍可能調整。
+`0.2.0-alpha` 是早期公開 alpha。API 已可用、已測試、可供回饋，但在 `1.0` 前仍可能調整。
 
-目前驗證基線：628 個 unit test 和 16 個 integration test 通過，2 個外部 smoke test 跳過，覆蓋率門檻為 90% line / 80% branch，單 jar 約 202 KB。
+目前驗證基線：645 個 unit test 和 16 個 integration test 通過，2 個外部 smoke test 跳過，覆蓋率門檻為 90% line / 80% branch，單 jar 約 205 KB。
 
 ## License
 

examples/evidence-overlay/README.md

@@ -35,7 +35,7 @@ Then compile + run the standalone example (no Maven submodule):
 ```bash
 JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \
   mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt
-CP="target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/cp.txt)"
+CP="target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/cp.txt)"
 javac -cp "$CP" -d /tmp/overlay-build examples/evidence-overlay/EvidenceOverlay.java
 java  -cp "/tmp/overlay-build:$CP" ai.doctruth.examples.evidenceoverlay.EvidenceOverlay
 ```

examples/pydantic-interop/README.md

@@ -17,7 +17,7 @@ runtime dependency.
 If your Python model is importable as `myapp.schemas:ResumeExtraction`:
 
 ```bash
-java -jar target/doctruth-java-0.1.0-SNAPSHOT.jar \
+java -jar target/doctruth-java-0.2.0-alpha.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   --out examples/pydantic-interop/resume.schema.json \
   --check
@@ -38,7 +38,7 @@ Build the jar and classpath:
 JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home \
   mvn -B -ntp package -DskipTests
 mvn -q dependency:build-classpath -Dmdep.outputFile=/tmp/doctruth-cp.txt
-CP="target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/doctruth-cp.txt)"
+CP="target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/doctruth-cp.txt)"
 ```
 
 Compile and run:

examples/quickstart/README.md

@@ -44,7 +44,7 @@ mvn exec:java \
 export OPENAI_API_KEY=sk-...
 mvn -q -f /path/to/doctruth-java/pom.xml package -DskipTests
 mvn -q -f /path/to/doctruth-java/pom.xml dependency:build-classpath -Dmdep.outputFile=/tmp/doctruth-cp.txt
-CP="/path/to/doctruth-java/target/doctruth-java-0.1.0-SNAPSHOT.jar:$(cat /tmp/doctruth-cp.txt)"
+CP="/path/to/doctruth-java/target/doctruth-java-0.2.0-alpha.jar:$(cat /tmp/doctruth-cp.txt)"
 javac -cp "$CP" -d build /path/to/doctruth-java/examples/quickstart/Quickstart.java
 java  -cp "build:$CP" ai.doctruth.examples.quickstart.Quickstart
 ```

pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>ai.doctruth</groupId>
     <artifactId>doctruth-java</artifactId>
-    <version>0.2.0-SNAPSHOT</version>
+    <version>0.2.0-alpha</version>
     <packaging>jar</packaging>
 
     <name>DocTruth</name>