Implement planned topic: 0017-jackson-3

[skill-temporal-developer-updater]

Validation Report — jackson-3 (Temporal Java SDK integration)

Branch: draft/0017-jackson-3
Files under validation:

• references/java/integrations/jackson-3.md (new, 132 lines)
• references/integrations.md (one row appended)

Source of truth: ../documentation/docs/, specifically:

• docs/develop/java/best-practices/converters-and-encryption.mdx
• docs/develop/java/workflows/basics.mdx
• docs/develop/java/activities/basics.mdx

---

Go/no-go

Check	Verdict
1. Citation audit	PASS — 10/10 (100%) ≥ 98%
2. Reverse-grep audit	PASS — zero unexplained grep-misses
3. Regression patterns	PASS — zero hits
4. Independent re-verification	PASS — 9/9 (100%) ≥ 95%
5. Integration-layout audit	PASS — all five sub-checks clean

Overall verdict: GO

The file is intentionally a "forward-looking" placeholder for a topic (Jackson 3 payload conversion) that is not yet documented in the local ../documentation/ clone. The authoring strategy — document the Jackson-2 status quo, then enumerate every Jackson-3 question with <!-- VERIFY: --> blocks and an explicit anti-fabrication checklist — is a sound response to that constraint. All factual claims in the file are grounded in cited docs; all unverified candidate names are explicitly framed as candidates to confirm or prohibitions.

---

Check 1 findings

None. All 10 cited spans resolve cleanly and substantively support the authored claims.

Citation	File	Lines	Resolved	Supports claim
1	converters-and-encryption.mdx	227-237	✓	✓
2	workflows/basics.mdx	150	✓	✓
3	activities/basics.mdx	75	✓	✓
4	converters-and-encryption.mdx	185-187	✓	✓
5	converters-and-encryption.mdx	207-209, 225-250	✓	✓
6	workflows/basics.mdx	150 (re-cite)	✓	✓
7	activities/basics.mdx	75 (re-cite)	✓	✓
8	workflows/basics.mdx	148	✓	✓
9	converters-and-encryption.mdx	229-251 (transcription tag)	✓	✓
10	converters-and-encryption.mdx	35-164	✓	✓

---

Check 2 findings

None. All factual Temporal-Java tokens resolve in the docs clone:

Token	Found in docs
JacksonJsonPayloadConverter	✓ converters-and-encryption.mdx
DefaultDataConverter	✓ (4 files including converters-and-encryption.mdx)
withPayloadConverterOverrides	✓ converters-and-encryption.mdx
newDefaultInstance	✓ converters-and-encryption.mdx
WorkflowClientOptions	✓ (10 files)
getEncodingType	✓ converters-and-encryption.mdx
setDataConverter	✓ converters-and-encryption.mdx
PayloadConverter	✓ (15 files)
ObjectMapper	✓ (5 files including converters-and-encryption.mdx)
"json/plain"	✓ converters-and-encryption.mdx (L208)

Non-Temporal token: tools.jackson.* (mentioned at line 13 of the skill). Properly tagged <!-- jackson-upstream: package rename and builder-only mapper construction in Jackson 3.x; treat as a Jackson-project fact, not a Temporal-documented fact -->. Acceptable.

Negative check (verifying the file's "not yet documented" framing is itself accurate): every <!-- VERIFY --> candidate name (Jackson3JsonPayloadConverter, useJackson3, withJackson3, newJackson3Instance, temporal-jackson3, "Jackson 3" prose) returned zero matches in the docs clone. The file's framing is accurate.

---

Check 3 findings

None.

• Universal regression patterns (--profile, TEMPORAL_TLS_CLIENT_CERT_PATH, tcld service-account, --output text|jsonl, saas-api.tmprl.cloud:7233, etc.): zero hits.
• Topic-specific regression patterns (Jackson3JsonPayloadConverter, useJackson3, withJackson3, newJackson3Instance, temporal-jackson3 appearing as factual claims rather than VERIFY candidates): every occurrence is correctly contained inside a <!-- VERIFY: --> block (lines 61-63, 73, 84) or inside the explicit anti-fabrication checklist that prohibits them (lines 107-109).

---

Check 4 findings

One minor nuance flagged; no substantive divergence.

Nuance (claim 4, file line 21):

• Authored: "Tokens that need conversion pass through each registered PayloadConverter in order; the first one whose encoding type matches handles the conversion."
• Docs (converters-and-encryption.mdx:185-187): "...passes through each Payload Converter in sequence until the converter that handles the data type does the conversion."

The cited paragraph is about the encoding direction, where dispatch is by data type. Encoding-type metadata (getEncodingType()) drives decoding dispatch. The authored sentence conflates the two directions. A reader following the authored version still calls withPayloadConverterOverrides correctly — the practical action is unchanged — so this is a conceptual nuance, not a substantive misdirection. Not enough to fail Check 4.

Minor wording drifts (claims 2, 3, 6, 7):

Docs say "should be serializable by the default Jackson JSON Payload Converter"; authored says "must be serializable". The strict-serializability requirement is stated as "must" elsewhere in the same docs (workflows/basics.mdx:144 — "All Workflow Definition parameters must be serializable"), so the strengthening is defensible. Not substantive.

Match rate: 9/9 = 100% (with the above non-substantive notes).

---

Check 5 findings

None.

Sub-check	Status
File location at references/java/integrations/jackson-3.md	✓
Exactly one new row in references/integrations.md with all five fields	✓
No SKILL.md edit	✓
No per-integration bullet in references/java/java.md	✓
No oversized inline cross-link blurb in ai-patterns.md or sibling	✓

Non-blocking consistency observation (not a Check 5 finding): the catalog row in references/integrations.md asserts the integration is "wire-compatible with existing Jackson 2 converters" as factual prose, while the reference file at line 13 flags exactly that claim as <!-- VERIFY: … planning-doc claim, not yet documented in ../documentation/ -->. The catalog row could be softened (e.g. "intended to be wire-compatible") to stay consistent with the reference file's own hedging. This is a tone/consistency note, not a layout finding.

---

Statistics

• Inline docs citations: 10 (across 3 distinct doc files)
• VERIFY-tagged candidate identifiers (negative-checked, expected absent in docs): 6 classes (class name, method names ×3, artifact ID, package root prose)
• Reverse-grep tokens checked: 10 Temporal-Java identifiers + 1 upstream-Jackson identifier (tagged) + 6 negative-check identifiers
• Grep-misses (factual tokens absent from docs): 0
• Regression-pattern hits: 0
• Check 4 sample size: 9 (the full set of inline-cited claims; smaller than the template's nominal 10 because the file's authoring strategy minimizes factual claims)
• Check 4 substantive match rate: 9/9 = 100%
• Check 5 sub-checks: 5/5 pass

---

Notes on authoring strategy (informational, not a finding)

The skill file deliberately documents a topic the docs clone does not yet cover. Rather than fabricate the Jackson 3 API surface, the author:

1. Established the Jackson 2 ground truth (cited).
2. Marked every Jackson-3-specific identifier the docs do not contain as <!-- VERIFY: -->.
3. Listed plausible-but-wrong candidates explicitly as forbidden ("Do not write a class name like Jackson3JsonPayloadConverter as if it existed").
4. Pre-identified the likely landing zone in the docs (converters-and-encryption.mdx) for the future Jackson 3 section.

This is exactly the anti-fabrication pattern the four-check protocol is designed to reward, and the file passes every check cleanly. GO.