Implement planned topic: 0017-jackson-3

[skill-temporal-developer-updater]

Validation Report — jackson-3

Branch: draft/0017-jackson-3
Scope validated: the working-tree modification to references/java/data-handling.md (the only delta against main; git log main..HEAD is empty — the change is uncommitted on this branch).
Filled plan: VALIDATION_PLAN.md.

Go / no-go

Check	Result	Notes
1 — Citation audit	PASS (with one weak citation)	4/4 docs citations resolve to existing lines. One citation (converters-and-encryption.mdx:227, used to anchor the "Jackson 2's JacksonJsonPayloadConverter" framing) is mechanically valid but does not support the version label in the cited sentence.
2 — Reverse-grep audit	PASS	All Java symbols (JacksonJsonPayloadConverter, DefaultDataConverter, WorkflowClientOptions, ObjectMapper) appear in docs/develop/java/. Jackson 3 is absent from the docs clone, as expected; that absence is tagged planned-content: or VERIFY:.
3 — Regression patterns	PASS	No hits on universal patterns (--profile, TEMPORAL_TLS_CLIENT_*, tcld service-account, --output text/jsonl, :7233) or topic-specific patterns (fabricated Jackson 3 symbol names).
4 — Independent re-verification	FAIL	Of 5 substantive claims in the new section, 2 fully match the cited sources, 2 are partial (sub-claims unsourced), and 1 has an uncited external-library claim. Strict match rate ≈ 40 %; sub-claim match rate ≈ 70 %. Both are below the 95 % threshold.
5 — Integration-layout audit	N/A	Topic is not a third-party plugin / contrib module — it is an internal Java SDK opt-in path. The diff correctly does not touch references/integrations.md and correctly does not create references/java/integrations/jackson-3.md.
6 — Tone and scope audit	FAIL	The new section gives prescriptive instructions ("Switch to the Jackson 3 path by calling the Jackson 3 opt-in startup API …") around an API whose exact symbol is VERIFY:-flagged as unknown. No Public-Preview / pre-GA admonition is present, despite the standard > [!NOTE] convention being used elsewhere in this skill for less-speculative features. An AI agent generating code against this section will produce code that references a nonexistent or fabricated symbol.

Overall verdict: RE-RUN AUTHORING

Triggered by Check 4 below the 95 % threshold and by Check 6 pattern 4/5 (prescriptive guidance on an unverified API surface, no admonition). The fundamental issue is that the entire ## Jackson 3 (opt-in) section is grounded on a pipeline-internal info.json topic stub and a VERIFY: tag, not on docs — so the skill is asking an AI agent to generate code for a feature that is not in the released documentation and whose API surface the author themselves does not yet know.

---

Check 1 findings

The four docs citations resolve to existing files and lines. Three of them carry their weight; one is on a borderline line for the specific claim it anchors.

Finding 1.1 — weak citation: line 227 for the "Jackson 2's" retronym

• File: references/java/data-handling.md:42
• Citation: <!-- docs/develop/java/best-practices/converters-and-encryption.mdx:227 -->
• Authored claim: "The Java SDK's default JSON path runs through Jackson 2's JacksonJsonPayloadConverter."
• Cited line 227: "For example, to create a custom JacksonJsonPayloadConverter, use the following:"
• The cited line confirms the class name exists. It does not state that JacksonJsonPayloadConverter is "the default JSON path" (that framing is supported elsewhere in the same file, around the DefaultDataConverter chain, but not at line 227), and it does not label the class as "Jackson 2's". The version label is an interpretive retronym introduced by the author to set up the Jackson-3 contrast; the docs clone never says "Jackson 2" anywhere.
• Severity: low. The substantive claim (the current default path uses Jackson via JacksonJsonPayloadConverter) is true and supported elsewhere. The citation just points at the wrong line for the version-label part of the claim.

Finding 1.2 — planned-content: citation usage

• File: references/java/data-handling.md:42 and :44
• Citation: <!-- planned-content: 0017-jackson-3/info.json -->
• The target file pipeline/planned-content/skill-temporal-developer/0017-jackson-3/info.json exists and contains: "description": "Java can opt into Jackson 3 payload conversion with a new startup API while remaining wire-compatible with Jackson 2 converters."
• This citation tag is non-standard (no other reference file in this skill uses planned-content:). It points at a one-sentence pipeline-internal description, not at documentation. Whether that is an acceptable grounding source for prescriptive content in a shipped skill is a design call for authoring — flagged for visibility.
• Severity: medium (design concern, not a mechanical citation error).

Check 2 findings

None. All Java type / class tokens introduced by the new section appear in docs/develop/java/best-practices/converters-and-encryption.mdx (and other Java docs). The Jackson 3 absence is expected and tagged.

Check 3 findings

None. No universal or topic-specific regression patterns appear in the modified file.

Check 4 findings

Per-claim breakdown. Claims numbered against §3 Check 4 of VALIDATION_PLAN.md.

Claim 1 — "The Java SDK's default JSON path runs through Jackson 2's JacksonJsonPayloadConverter."

• Cited source: converters-and-encryption.mdx:227.
• What the cited line actually says: "For example, to create a custom JacksonJsonPayloadConverter, use the following:".
• Match? Partial. The class-name part is supported. The "default JSON path" framing is supported elsewhere in the same docs file but not at the cited line. The "Jackson 2's" version label is not in the docs at all.
• Substantively different action for an agent? Marginal. An agent reading the authored text understands they should use JacksonJsonPayloadConverter for the current path. The "Jackson 2" retronym doesn't change generated code.

Claim 2 — "A separate Jackson 3 payload-conversion path is available as an opt-in, selected via a new startup API."

• Cited source: planned-content/0017-jackson-3/info.json.
• info.json says: "Java can opt into Jackson 3 payload conversion with a new startup API …".
• Match? Yes. Faithful paraphrase.

Claim 3 — "Payloads written by the Jackson 3 path remain readable by Jackson 2 converters on the other side of the wire, and vice versa — a worker on Jackson 3 can interoperate with a client still on Jackson 2 without re-encoding history."

• Cited source: planned-content/0017-jackson-3/info.json.
• info.json says only: "remaining wire-compatible with Jackson 2 converters".
• Match? Partial. The bidirectional reading is a reasonable interpretation of "wire-compatible". The clause "without re-encoding history" extends the source — "wire-compatible" does not strictly imply that already-written histories require no migration. The extension may be true but is unsourced.
• Substantively different action for an agent? Yes. An agent told "no re-encoding history" will confidently advise the user not to plan a backfill / migration step when switching workers from Jackson 2 to Jackson 3, even though the source (info.json) does not actually make that claim.

Claim 4 — "Switch to the Jackson 3 path by calling the Jackson 3 opt-in startup API … when constructing your DefaultDataConverter, then install the converter on WorkflowClientOptions the same way as today."

• Cited source: converters-and-encryption.mdx:239,247.
• Line 239 confirms the override-via-withPayloadConverterOverrides-on-DefaultDataConverter-in-WorkflowClient-options pattern. Line 247 is the code line .withPayloadConverterOverrides(new YourCustomPayloadConverter());.
• Sub-claim a ("calling the Jackson 3 opt-in startup API … when constructing your DefaultDataConverter"): unverified — explicitly flagged by the in-line VERIFY: comment. The phrase "when constructing your DefaultDataConverter" gives the timing but not the call; an agent has no way to produce concrete code from this without inventing a symbol.
• Sub-claim b ("install the converter on WorkflowClientOptions the same way as today"): matches lines 239 and 247.
• Substantively different action for an agent? Yes, badly. An agent told to "call the Jackson 3 opt-in startup API" with no name will either fabricate (enableJackson3(), withJackson3(), JacksonJson3PayloadConverter, etc.) or stop and ask the user. The first path produces broken code; the second negates the value of having the section. The VERIFY: tag is in an HTML comment, so its visibility to an agent depends on how the agent reads the file.

Claim 5 — "Customising the underlying ObjectMapper (modules, serialisation features) is still how you tune behaviour — Jackson 3's ObjectMapper lives in a different package and is constructed through a builder, so the surrounding Jackson 2 idiom in the section above does not transfer verbatim."

• No citation tag on this sentence (the preceding citation :239,247 is anchored on the prior sentence).
• Sub-claim a ("ObjectMapper customisation is still how you tune behaviour"): supported by the existing Jackson Integration section and by docs line 232.
• Sub-claim b ("Jackson 3's ObjectMapper lives in a different package and is constructed through a builder"): no citation in the authored file, not in the docs clone, not in info.json. The claim is about an external library (Jackson 3 itself) and the skill has no source for it. Whether or not it is factually true of Jackson 3, the skill's citation convention is bypassed here — there is no <!-- jackson: … -->, no <!-- VERIFY: … -->, no <!-- undocumented: … -->. The author is asserting a fact from training-data memory.

Tally.

• 5 top-level claims, 7 sub-claims.
• Fully matches the cited source: claim 2; claim 4 sub-claim b; claim 5 sub-claim a → 3 of 7 sub-claims.
• Partial / unsourced extensions: claim 1 (version label); claim 3 (no re-encoding extension); claim 5 sub-claim b (no citation) → 3 of 7 sub-claims.
• Acknowledged-unverified (VERIFY: tag): claim 4 sub-claim a → 1 of 7 sub-claims.
• Pass rate (matches / total sub-claims) = 3/7 ≈ 43 %. Below the 95 % threshold.

Check 5 findings

Not applicable (see Go/no-go row 5).

Check 6 findings

Finding 6.1 (MAJOR) — prescriptive guidance against an unverified API surface, no admonition.

• File: references/java/data-handling.md:46.
• The "Opt-in call site" paragraph reads:

  Opt-in call site. Switch to the Jackson 3 path by calling the Jackson 3 opt-in startup API <!-- VERIFY: exact symbol (class / static method / builder option) for the Jackson 3 opt-in is not yet in ../documentation/docs/develop/java/; needs sdk-java release notes or javadoc --> when constructing your DefaultDataConverter, then install the converter on WorkflowClientOptions the same way as today.

• The instruction is imperative ("Switch to the Jackson 3 path by calling …") but the symbol to call is explicitly unknown. The VERIFY: comment is inside an HTML comment block; the prose around it reads as confident, finished instruction.
• An AI agent generating Java code from this paragraph has three behaviours, all bad: (a) invent a symbol; (b) refuse and ask the user; (c) silently drop the Jackson-3 part. Without a leading admonition flagging that the API is not yet released / not yet documented, behaviour (a) is the most likely.
• Compare to references/java/integrations/spring-ai.md:9-10, which uses the standard convention for a less-speculative case (Spring AI integration is released and documented):

  > [!NOTE]
  > This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.
  

• The Jackson-3 section warrants an even stronger admonition (something like "this feature is not yet released; do not generate code that references the opt-in API symbol — wait for the Jackson 3 release notes / javadoc"). The current section has none.

Finding 6.2 (MINOR) — uncited factual claim about Jackson 3's ObjectMapper package and builder.

• File: references/java/data-handling.md:46, second half ("Jackson 3's ObjectMapper lives in a different package and is constructed through a builder, so the surrounding Jackson 2 idiom in the section above does not transfer verbatim.").
• This is an out-of-skill, uncited claim about an external library. Either remove the half-sentence, tag it with the appropriate non-docs source category (Jackson javadoc URL), or move it into the same "VERIFY/Public-Preview" admonition that addresses finding 6.1.

Finding 6.3 (MINOR) — "no behavioural gain" framing in "When to opt in" bullet.

• File: references/java/data-handling.md:51.
• The bullet says: "Stay on the default Jackson 2 path otherwise — there is no behavioural gain to switching in an app that has no Jackson 3 requirement."
• This is acceptable per Check 6 (it states a constraint plus the supported alternative) but the "no behavioural gain" claim is an assertion the docs do not make. If the Jackson 3 path differs in any subtle serialization behaviour (date formatting, default null handling, etc.), the bullet over-promises. Soften to "no Temporal-side reason to switch" or drop the half-clause.
• Not blocking on its own.

No workaround disclosures (pattern 1) detected. The section does not show the agent how to circumvent any documented constraint — it offers a supported (if unreleased) opt-in path.

---

Statistics

• Citation comments in diff (counting both new and added-to existing lines): 5 (3 docs, 2 planned-content; 1 VERIFY is informational and not counted as a citation).
• Docs citations resolving to existing file:line: 4 / 4 = 100 %.
• Docs citations whose cited line fully supports the anchored claim: 3 / 4 = 75 %.
• Token reverse-grep misses (Java symbols): 0 / 4.
• Regression pattern hits: 0.
• Check 4 sub-claim match rate: 3 / 7 ≈ 43 % (threshold 95 %).
• Check 6 findings: 1 MAJOR (pattern 4 — missing pre-GA admonition around a prescriptive section), 2 MINOR.

---

Recommendation

RE-RUN AUTHORING on references/java/data-handling.md lines 40–53. Two options for the next pass:

1. Defer. Wait until the Jackson 3 opt-in API lands in docs/develop/java/ (and/or sdk-java release notes / javadoc). Then re-author the section against real symbols. Until then, do not ship a prescriptive opt-in section.
2. Reframe as a "heads-up" admonition. If shipping early is required, replace the prescriptive paragraph with a non-prescriptive note: "A Jackson 3 opt-in path is planned. The exact opt-in API is not yet documented; do not generate code that references it. When it ships, the conversion installs on WorkflowClientOptions the same way as the existing Jackson 2 path." Plus the standard > [!NOTE] Public-Preview-style admonition. Drop claim 5 sub-claim b or move it under the same admonition.

Authoring should also:

• Either anchor the "Jackson 2" version label on a real docs line (or drop the retronym).
• Either source the "without re-encoding history" extension of "wire-compatible" or remove it.
• Either source or remove the claim about Jackson 3's ObjectMapper package/builder.

End of report.