Implement planned topic: 0021-memo-data-converter

[skill-temporal-developer-updater]

Skill Validation Report — memo data converter

Branch: draft/0021-memo-data-converter
Scope of change: references/go/data-handling.md only (+22 lines). New H3 section Memo encoding: default vs. user DataConverter plus one new Best Practices bullet. No SKILL.md, references/integrations.md, language-entry-point, or new-file changes.
Topic class: Temporal SDK feature (not a third-party integration) — Check 5 skipped.
Validation date: 2026-05-14

---

Go/no-go

Check	Result	Threshold
1. Citation audit	FAIL	9/12 resolve cleanly (75%) — threshold ≥ 98%
2. Reverse-grep audit	PASS	0 unexplained misses
3. Regression on known bugs	PASS	0 universal-pattern hits
4. Independent re-verification	PASS	13/13 sampled claims match (100%) — threshold ≥ 95%
5. Integration-layout audit	N/A	Not an integration topic
6. Tone and scope audit	PASS	0 Pattern-1 (workaround-disclosure) findings

Overall verdict (strict rubric): RE-RUN AUTHORING. Check 1 falls below threshold.

Narrow-scope note for maintainer judgment: the Check 1 failures are exclusively wrong-line citations on internal/internal_flags.go (3 occurrences). Every claim is independently verifiable, and the correct line in the same file is within ~10 lines of the cited line. A targeted patch fixing the three line numbers — without re-authoring the section — would lift Check 1 to 12/12 and convert the verdict to GO. The maintainer can choose to honor the strict rubric and re-run authoring, or treat this as a localized line-number fix.

---

Check 1 findings — wrong line numbers on sdk-go citations

All three findings are on the same source file (temporalio/sdk-go internal/internal_flags.go) and all three cite a line that does not contain the claimed content; the actual line is elsewhere in the same file. Content claims are accurate.

Finding 1.1 — data-handling.md:260

• Cited: <!-- sdk-go: internal/internal_flags.go @ v1.41.0:67 (sdkFlagsAllowed[SDKFlagMemoUserDCEncode] = false) -->
• Cited line content (v1.41.0:67): // — a blank comment line inside the doc-comment block above loadFlagOverridesFromEnv.
• Actual location of claim: v1.41.0 line 56 — SDKFlagMemoUserDCEncode: false, inside the sdkFlagsAllowed map.
• Line offset: −11.

Finding 1.2 — data-handling.md:263

• Cited: <!-- sdk-go release notes v1.41.0; sdk-go: internal/internal_flags.go @ v1.41.0:46 --> (for the claim SDKFlagMemoUserDCEncode numeric ID 7)
• Cited line content (v1.41.0:46): // New flags should default to false until at least one release after introduction. — a comment in the sdkFlagsAllowed doc block, unrelated to the flag's numeric value.
• Actual location of claim: v1.41.0 line 39 — SDKFlagMemoUserDCEncode = 7 inside the const block.
• Line offset: −7.
• Note: the release-notes citation portion is correct — v1.41.0 release notes do reference PR #2121 introducing this flag, though the notes do not name the flag identifier.

Finding 1.3 — data-handling.md:267

• Cited: <!-- sdk-go: internal/internal_flags.go @ v1.43.0:67 --> (for the claim that the flag is disabled by default in v1.41.0 through v1.43.0)
• Cited line content (v1.43.0:67): // — same blank comment line as Finding 1.1 (file structure unchanged across the version range).
• Actual location of claim: v1.43.0 line 56 — SDKFlagMemoUserDCEncode: false,.
• Line offset: −11.

Check 1 — citations that resolved cleanly (9/12)

Line in skill	Citation	Status
261	docs/develop/go/best-practices/data-handling/data-encryption.mdx:104-118	✓ Section "Step 2: Set Data Converter to use custom Payload Codec" with client.Dial example. Supports the "encrypts Workflow inputs/results" framing.
263	sdk-go release notes v1.41.0	✓ Release notes contain the bullet "Introduce SDK flag to use user DC on Memo's by @yuandrew in #2121".
264	sdk-go PR #2121 file list (internal_workflow_client.go, internal_schedule_client.go, internal_event_handlers.go)	✓ All three files are in the PR's changed-files list.
265	sdk-go PR #2121: encodeMemoValue in internal/internal_workflow_client.go	✓ Function is defined in that file: func encodeMemoValue(value interface{}, dc converter.DataConverter, useUserDC bool) (*commonpb.Payload, error).
268	sdk-go: internal/internal_flags.go @ v1.41.0 (no specific line, for loadFlagOverridesFromEnv env-var pattern)	✓ Lines 71–83 in v1.41.0 define loadFlagOverridesFromEnv building fmt.Sprintf("TEMPORAL_SDK_FLAG_%d", flag) (L73) and accepting "1" / "0" (L76, L78).
269	sdk-go PR #2121 introduces no new exported ClientOptions/WorkerOptions field	✓ PR's exported-API surface review surfaces no new ClientOptions / WorkerOptions field; opt-in is via env var only.
271	docs/develop/go/best-practices/data-handling/data-encryption.mdx:37-44, 112-117	✓ L41–44 show converter.NewCodecDataConverter(...) construction; L112–117 show client.Dial(client.Options{DataConverter: ...}).
275	sdk-go PR #2121: getWorkflowMemo is memo-only	✓ getWorkflowMemo returns *commonpb.Memo — does not touch search attributes.
276	sdk-go PR #2121: internal/internal_event_handlers.go (TryUse-gated in-workflow paths)	✓ Event-handlers file contains wc.TryUse(SDKFlagMemoUserDCEncode) at both UpsertMemo and ExecuteChildWorkflow call sites.
277	docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx:169-181	✓ L169 ("non-indexed metadata"), L179 ("lack type safety"), L180 ("eventual consistency") — all three quoted attributes verbatim or paraphrased.

(Counted as 10 cleanly-resolved citation tags but I list 12 distinct citation comments — discrepancy is that L268 and L264 each compound multiple sources within a single comment. The 9/12 ratio reflects 12 distinct citation comments in the section, 3 of which contain wrong-line failures.)

---

Check 2 findings — none

Every factual token in the new section was located in the source-of-truth corpus. Tokens checked and resolved:

• SDK-internal symbols: SDKFlagMemoUserDCEncode (sdk-go internal/internal_flags.go:37,39,56), sdkFlagsAllowed (L49), loadFlagOverridesFromEnv (L71), encodeMemoValue (PR #2121, internal_workflow_client.go), getWorkflowMemo (PR #2121, three files), TryUse (PR #2121, internal_event_handlers.go — capitalized form at workflow-context call sites; distinct from lowercase tryUse method on sdkFlags).
• Env var: TEMPORAL_SDK_FLAG_7 — derived from fmt.Sprintf("TEMPORAL_SDK_FLAG_%d", flag) with the verified flag-ID value 7.
• Numeric flag ID: 7 — internal/internal_flags.go v1.41.0:39.
• SDK versions: v1.41.0, v1.43.0 — both valid published releases; both show SDKFlagMemoUserDCEncode: false in sdkFlagsAllowed.
• PR identifier: #2121 — verified at github.com/Introduce SDK flag to use user DC on Memo's sdk-go#2121.
• Go SDK public APIs invoked: StartWorkflow, SignalWithStartWorkflow, ScheduleClient.Create, workflow.UpsertMemo, workflow.ExecuteChildWorkflow, client.Dial, client.Options, worker.Options, DataConverter, PayloadCodec, CodecDataConverter, converter.NewCodecDataConverter — all are standard, documented Go SDK identifiers found in the data-encryption.mdx source and the surrounding data-handling.md file.

---

Check 3 findings — none

Grep across the new section for the universal regression patterns (--profile, TEMPORAL_TLS_CLIENT_CERT_PATH, TEMPORAL_TLS_CLIENT_KEY_PATH, TEMPORAL_TLS_SERVER_CA_CERT_PATH, tcld service-account, --output text|jsonl, saas-api.tmprl.cloud:7233) returned zero matches.

---

Check 4 findings — none

Sampled all 13 distinct claims in the new section (sampling exhaustively rather than choosing 10, because the entire diff is 22 lines and small enough to cover fully). For each claim, I re-read the relevant docs section or sdk-go source independently and compared my own phrasing to the authored text. All 13 matched substantively. Notable nuances confirmed:

• C5 ("On encode error, the SDK falls back to the default Data Converter; if the default also errors, the user converter's error is returned") — matches the documented behavior of encodeMemoValue: attempts user DC first when useUserDC=true, falls back to default DC, and surfaces the user converter's error if both fail.
• C9 ("every client process and worker process that writes Memos") — independently identified that Memo writes occur in both client-side paths (StartWorkflow, SignalWithStartWorkflow, ScheduleClient.Create) and worker-side paths (UpsertMemo, ExecuteChildWorkflow), so the requirement to set the env var on both process classes is accurate.
• C11 ("the flag is gated through TryUse, so the decision is recorded in history and replay stays deterministic") — TryUse records the flag use into sf.newFlags, which the SDK then sends to the server so replay decisions can be reproduced. Match.
• C12 (quoted phrase "non-indexed metadata") — verbatim in workflow-execution.mdx:169.

---

Check 5 — N/A

Not a third-party integration topic. The diff does not modify references/integrations.md, does not add files under references/{lang}/integrations/, and does not edit SKILL.md or any language entry-point. Check skipped per template.

---

Check 6 findings — minor, non-gating

No Pattern 1 (workaround-disclosure) findings

The new section teaches a single mechanism to enable the flag: TEMPORAL_SDK_FLAG_7=1. This is the only documented public-surface way to enable SDKFlagMemoUserDCEncode in the v1.41.0–v1.43.0 range (PR #2121 added no exported ClientOptions / WorkerOptions field). The skill explicitly states "the env var is the only knob" — accurate.

The SDK source code's own comment characterizes env-var flag-flipping as "strongly discouraged… an emergency mechanism" (internal_flags.go L68–70). I considered whether teaching the env var to agents disclosed a workaround. Concluded no, because (a) there is no alternative public mechanism, (b) the flag is documented and intentional, (c) the skill correctly frames it as opt-in rather than as a hack. The discouraged-in-source nature is worth a maintainer note but not a Check 6 finding.

Borderline Pattern 2/3 (in-the-weeds rationale) — flagged for optional tightening

• data-handling.md:265 — the fallback-order detail ("On encode error, the SDK falls back to the default Data Converter; if the default also errors, the user converter's error is returned") is implementation-detail-grade. An agent writing user code does not branch on which DC's error surfaces. This sentence could be removed without changing generated code.
• data-handling.md:276 — the rationale tail "…so the decision is recorded in history and replay stays deterministic" explains a replay-safety guarantee. The agent will not write code that depends on this guarantee; the rationale doesn't change output. Could be tightened to just "For in-Workflow calls (UpsertMemo, ExecuteChildWorkflow), the flag is gated through TryUse."

Neither finding triggers a re-author. Bundle into a follow-up commit if the rest of the section is being touched.

No Pattern 4 (Public Preview admonition) finding

The cited docs do not flag this feature as Public Preview; the v1.41.0 release notes do not flag it as preview. Standard [!NOTE] admonition not applicable.

---

Statistics

• Files modified by branch: 1 (references/go/data-handling.md)
• New lines added: 22
• Distinct citation comments in new section: 12
• Citations resolving cleanly: 9 (75%)
• Citations with wrong-line failures: 3 (all on temporalio/sdk-go internal/internal_flags.go)
• Citations with wrong-file or wrong-content failures: 0
• Factual tokens reverse-grepped: ~20; unexplained misses: 0
• Regression-pattern matches: 0
• Claims sampled for Check 4: 13 of 13 distinct claims (exhaustive); matches: 13/13 (100%)
• Tone/scope Pattern-1 findings: 0
• Tone/scope Pattern-2/3 findings: 2 (non-gating)