[WP8] Native-image / AOT: user-POJO hints uncovered + nativeTest never run in CI #202

此內容由 AI 產生（specification-mapper 全庫審查 2026-07-16．執行圖）。

Work package WP8 · findings: COR-04, TEST-02 · worst severity: medium · effort: M

From the 2026-07-16 whole-codebase review of branch jakarta (snapshot 7de4a33; modules mapper/ + starter/). Every finding below is CONFIRMED by independent adversarial verification. File:line coordinates are from the snapshot and may have drifted.

Findings

COR-04 — Native-image reflection hints cover only jars shipping their own Jandex index; user query POJOs are silently unfiltered, and the contract is undocumented (correctness, medium)

• File: mapper/src/main/java/tw/com/softleader/data/jpa/spec/aot/SpecMapperRuntimeHints.java:50
• Evidence: runtime hints are registered only for classes discoverable via the mapper's own Jandex index (reflect-config.idx). A consumer's query POJOs and custom spec classes — the ones actually reflected over at runtime — get no hints, and nothing documents that the consumer must supply them. Under native image, reflection on those classes fails at runtime.

TEST-02 — nativeTest profile is never exercised by any CI pipeline (testing, medium)

• File: Jenkinsfile:107
• Evidence: the nativeTest (GraalVM) profile exists but no pipeline runs it, so an AOT/native regression ships green.

Design decision needed

COR-04's remedy is a maintainer-owned API/contract choice:

• (a) Document the reflect-config.idx contract: state that consumers must ship their own Jandex index (or register hints), keeping the mapper's footprint minimal but pushing work onto every consumer.
• (b) Ship a starter AOT BeanFactoryInitializationAotProcessor that discovers consumer query POJOs and registers their hints automatically — better DX, but new AOT machinery in the starter to design, test, and maintain.
• (c) Both — a processor for the common case plus documented escape hatch.

TEST-02 is independently workable (add make test-native to CI), but it only pays off once native support is deliberately maintained — which is what the COR-04 decision settles. Once the direction is chosen, add a Plan and swap status: pending-design-work for status: ready-for-agent.

Acceptance criteria (target)

• Native reflection over consumer query POJOs is either automatically hinted (option b/c) or the contract for supplying hints is documented (option a) — a native-image consumer no longer fails silently at runtime.
• A CI job runs make test-native (GraalVM) so native regressions are caught.
• Regression: make test green.