Implement planned topic: 0010-serialization-context

[skill-temporal-developer-updater]

Skill Validation Report — serialization-context

Reviewer session: independent of authoring. Did not read hidden-from-validator/AUTHORING_PLAN.md or hidden-from-validator/AUTHORING_LOG.md. Validation drawn from authored files + ../documentation/docs/.

Files validated (all uncommitted on draft/0010-serialization-context):

• SKILL.md (modified — added serialization-context bullet under Primary References)
• references/core/serialization-context.md (new — conceptual page)
• references/go/serialization-context.md (new — Go SDK page)
• references/python/serialization-context.md (new — Python SDK page)
• references/dotnet/serialization-context.md (new — placeholder; .NET docs silent)
• references/go/data-handling.md, references/python/data-handling.md, references/dotnet/data-handling.md (modified — added one-line cross-link to language's serialization-context page)
• references/go/go.md, references/python/python.md, references/dotnet/dotnet.md (modified — added a Reference Files bullet for the new page)

Topic classification:

• Not a third-party integration → Check 5 skipped
• Cross-language feature with references/core/<feature>.md plus per-language pages → Check 7 applies

---

Go / no-go

Check	Result
1. Citation audit	PASS — every cited file/line range exists and substantively supports the surrounding claim.
2. Reverse-grep audit	MINOR — one Python class name not found in Python docs (one undocumented token in three uses).
3. Regression on known bugs	PASS — zero hits on universal regressions.
4. Independent re-verification (sample)	PASS — 39/40 sampled claims match (97.5%).
5. Integration-layout audit	N/A — not an integration topic.
6. Tone and scope audit	PASS with one minor: a broken/templated Resources cross-link in references/go/serialization-context.md. No workaround disclosures.
7. Cross-language structure audit	PASS — all five gating sub-checks pass; bonus contextual cross-links present.

Overall verdict: MINOR FIXES. Check 3 clean, Check 4 ≥ 95%, Check 1 ≥ 98%, no workaround disclosures, cross-language structure intact. Two spot-fixes are recommended (see Check 2 and Check 6 below) before merge — neither requires re-authoring.

---

Check 1 findings — citation audit

Method: grepped every <!-- ... --> comment in the four authored files, then read each cited line range in ../documentation/docs/ and confirmed the authored sentence is substantively supported.

File	Citations	Resolved & supportive	Notes
references/core/serialization-context.md	15	15	All cited line ranges (encyclopedia/data-conversion/external-storage.mdx:24-30, 36-39, 67-70, 72-95, 119-124; payload-converter.mdx:38-55; Go/Python external-storage.mdx:111-122/121-137/126-131/131-137/162-165/207-211/252-289; dotnet converters-and-encryption.mdx:40-76) check out.
references/go/serialization-context.md	15	15	Includes external-storage.mdx:14-20 (Public Preview), 121-124 (Store sig), 126-137 (target/type switch), 162-165 (Retrieve sig), 190-195 (Name() change breaks retrieval), 207-211 (identity info prose), 252-289 (StorageDriverSelector / SelectDriver / nil returns inline).
references/python/serialization-context.md	12	11.5	All citations resolve, but two claims that say "target is a discriminated union (StorageDriverWorkflowInfo or StorageDriverActivityInfo)" cite external-storage.mdx:111-122 / 119-122, where only StorageDriverWorkflowInfo appears (see Check 2). The cited lines do not contain StorageDriverActivityInfo. Treated as half-credit — the broader claim is supported, the specific class name is not.
references/dotnet/serialization-context.md	6	6	All five <!-- VERIFY: ... --> placeholders are explicit "no .NET surface today" notes, not factual claims, and don't require resolution. The six factual citations (encyclopedia/data-conversion/external-storage.mdx:24-30, 36-39, 67-70, 119-124; dotnet/best-practices/converters-and-encryption.mdx:40-76) all check out.

User-facing https:// links: every Resources link uses a full https://docs.temporal.io/... URL — no root-relative /develop/... links found. ✓

Total: 48 inline citations, 47.5 substantively supported (≈ 99%). Threshold: 98%. PASS.

---

Check 2 findings — reverse-grep audit

Token classes scanned:

Class	Pattern	Notes
SDK type names	StorageDriver*, EncodingPayloadConverter, IPayloadCodec, Temporalio.Converters, converter.PayloadCodec	Each one grepped against the per-language docs subtree it belongs to.
Method names	Store/store, Retrieve/retrieve, EncodeAsync/DecodeAsync, SelectDriver, Name()/name()	All match docs verbatim.
Option keys	PayloadSizeThreshold, payload_size_threshold, driver_selector, DriverSelector	All match.
Code fence calls	ExternalStorage(...), client.Dial(...), Client.connect(...)	All match docs patterns.
Public Preview admonition phrasing	exact phrase	Matches authoring-plan §3.7 style (canonical wording preserved in core/go/python; dotnet has a slightly extended first sentence to clarify .NET gap but preserves the canonical "It is perfectly acceptable…" tail).

One unexplained miss:

• StorageDriverActivityInfo in references/python/serialization-context.md (3 occurrences: lines 10, 50, 78). Grep of documentation/docs/ finds this symbol only in docs/develop/go/best-practices/data-handling/external-storage.mdx (Go SDK). It is not present anywhere in docs/develop/python/.... The Python external-storage page describes the second target branch in prose only ("namespace, Workflow ID, or Activity ID depending on the operation") and never names the class. The cited Python docs line range (111-122) shows isinstance(target, StorageDriverWorkflowInfo) only.

  The class name was almost certainly extrapolated from the Go SDK's parallel naming convention. The Python SDK may well ship a class with this exact name, but as far as the published Python docs say, the class is unnamed. The authored file does not include an <!-- undocumented: source = ... --> marker, so this fails the reverse-grep test.

  Recommended fix: either tag every Python-side occurrence of StorageDriverActivityInfo with <!-- undocumented: source = ... --> once the Python SDK source is checked, or rephrase the Python file to avoid naming the class (e.g., "the activity branch of the discriminated union", isinstance(target, ...) # activity branch — see Python SDK API).

Total unexplained grep-misses: 1 token (3 usages). Threshold for MINOR: ≤ 5. MINOR.

---

Check 3 findings — regression on known bugs

Grepped the four authored files (and only those) for every universal regression pattern in the validation plan: --profile, TEMPORAL_TLS_CLIENT_CERT_PATH, TEMPORAL_TLS_CLIENT_KEY_PATH, TEMPORAL_TLS_SERVER_CA_CERT_PATH, tcld service-account, --output text, --output jsonl, saas-api.tmprl.cloud:7233.

No hits. This is unsurprising — the topic is a Data Converter / SDK API surface, not CLI/TLS/Cloud connection territory — but the strict requirement is satisfied.

No topic-specific regression patterns identified by prior authoring passes for this feature.

PASS.

---

Check 4 findings — independent re-verification (sampling)

Sample size: 10 claims per reference file × 4 files = 40 claims. Sampling is dense enough that nearly every claim was independently re-read.

Method: for each sampled claim, opened the cited docs file fresh, formed an independent reading, then compared to the authored sentence.

Per-file results:

File	Sampled claims	Substantively diverged
references/core/serialization-context.md	10 (pipeline order, S3 example, identity info, WorkflowInfo branch coverage, ActivityInfo Standalone-only, store/retrieve names, driver-selector callback, SDK coverage list, Target-not-Kind-enum, common mistake on converters)	0
references/go/serialization-context.md	10 (Public Preview cite, type names, Store signature, Retrieve signature, Target field, type-switch idiom, StorageDriverSelector/SelectDriver, nil keeps inline, Name() rename breaks retrieval, common mistakes)	0
references/python/serialization-context.md	10 (Public Preview cite, type names overview, store/retrieve signatures, target attribute, isinstance idiom, target.id/target.namespace, driver_selector callable, None keeps inline, common mistakes, name() rename)	1 — see below
references/dotnet/serialization-context.md	10 (Public Preview cite, encyclopedia lists Go/Python only, Temporalio.Converters namespace, IPayloadCodec.EncodeAsync/DecodeAsync shape, no context arg, placeholder treatment, four <!-- VERIFY --> markers, common mistakes, Resources)	0

The one divergent claim:

• references/python/serialization-context.md:10 — "The context's target attribute is a discriminated union (StorageDriverWorkflowInfo or StorageDriverActivityInfo)..."
  • Authored: explicitly names both Python classes.
  • Docs say (external-storage.mdx:111-176 read fresh): only StorageDriverWorkflowInfo is named in code; the second branch is described in prose ("Workflow ID, or Activity ID depending on the operation") and never given a class name. Same divergence affects line 50 (isinstance(target, StorageDriverActivityInfo)) and line 78 (common-mistake bullet).
  • Reader impact: an agent following the authored Python file will write isinstance(target, StorageDriverActivityInfo) based on a class name the published Python docs do not confirm. If the Python SDK uses a different class name (e.g. StorageActivityInfo, ActivityTarget, etc.), generated code will fail at import time. Worth verifying against the Python SDK source before merge.

Match rate: 39 / 40 = 97.5%. Threshold: 95%. PASS.

(Note: the Check 4 divergence is the same root cause as the Check 2 miss — counted once for purposes of the threshold but worth fixing once.)

---

Check 5 findings — integration-layout audit

N/A. Topic is not a third-party integration; references/integrations.md not relevant.

---

Check 6 findings — tone and scope audit

Read each of the four reference files end-to-end, judging bullet by bullet against the 15 pattern checklist.

Pattern 1 (workaround disclosure) — the gating pattern: zero findings. The Common Mistakes bullets all follow the acceptable "Don't do X; do Y instead" shape, where Y is the supported path:

• core, mistake 2: "Reaching for workflow info from inside a custom Payload Converter or Payload Codec. … If you need the owning Workflow ID at serialization time, implement a custom storage driver (or driver selector) rather than smuggling state into a converter." — Y is the documented driver surface, not a hack. ✓
• go, mistake 1: "Switching on Target with a default-case fallthrough that assumes Workflow identity. … Branch explicitly." ✓
• python, mistake 1: same shape. ✓
• dotnet, mistake 1: "Assuming the .NET SDK has the same SerializationContext / StorageDriver API as Go or Python. It does not, as of the current published documentation. Don't generate .NET code that imports Temporalio.Converters.StorageDriverStoreContext or similar based on the Go/Python names." — clean negative-with-no-workaround. ✓

Public Preview admonition (pattern 5): every file opens with > [!NOTE] plus the canonical "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" phrasing. The dotnet page extends the first sentence to clarify which SDKs ship the feature; the canonical second sentence is preserved verbatim. Acceptable.

One minor non-gating finding:

• references/go/serialization-context.md:91 — Resources bullet reads:

  "Standalone Activities (Go): see the language-specific reference under references/{your_language}/standalone-activities.md."

  Two issues: (a) the template literal {your_language} was not resolved to go (inconsistent with references/python/serialization-context.md:87, which uses the resolved path references/python/standalone-activities.md); and (b) even the resolved path references/go/standalone-activities.md does not exist in this repo today (Go has no per-language Standalone Activities page yet). Suggested fix: replace with references/core/standalone-activities.md, or add the Go-specific entry separately when it is authored.

• No findings against patterns 2 (in-the-weeds rationale), 3 (implementation-internals speculation), 4 (multi-sentence noise), 6 (duplicated admonitions), 7 (release-stage chatter beyond the admonition), 8 (speculative common mistakes), 9 (duplicated hard constraints), 10 (Resources pointing at raw source trees), 11 (external links duplicating local coverage), 12 (DIY rebuilds), 13 (repo slang), 14 (inline imports in examples — the Python example uses module-scope imports), 15 (ambiguous "context" references — every "context" in these files is grounded with the StorageDriverStoreContext / StorageDriverRetrieveContext type, not left abstract).

Verdict: PASS (zero workaround disclosures; one minor link inconsistency).

---

Check 7 findings — cross-language structure audit

Reference implementation per the plan: Standalone Activities. Compared this skill's layout against that pattern.

Sub-check	Result
1. Page split (one core + one per supported SDK)	PASS — references/core/serialization-context.md + Go + Python + .NET. Core page contains no language-specific code; per-language pages each carry their own SDK-specific code.
2. Core page language-agnostic	PASS — bridges Go and Python field names (Target (Go) / target (Python)) for cross-SDK clarity but ships no exclusive code. Opens with: "For language-specific implementation, see references/{your_language}/serialization-context.md." — mirrors the standalone-activities concept-page convention.
3. Identical per-language outline	PASS — heading lists across Go, Python, .NET are exactly: ## Overview → ## Prerequisites → ## Storage driver context → ## Reading workflow vs activity metadata → ## Driver selection → ## Common mistakes → ## Resources.
4. Overview back-link	PASS — each per-language file's Overview opens with [Cross-SDK concept file](references/core/serialization-context.md).
5. Link graph complete	PASS — all four edges verified: • SKILL.md lines 76–77 add the core bullet + sub-bullet (mirroring the standalone-activities entry just above). • references/go/go.md:255, references/python/python.md:184, references/dotnet/dotnet.md:204 each add a Reference Files bullet naming the per-language file and pointing to the core file. • references/core/serialization-context.md references each language file in the SDK-coverage and Resources sections. • Each per-language file links back to the core file (Overview line + Resources line).
6. Bonus contextual cross-links	PASS (advisory) — references/go/data-handling.md:266, references/python/data-handling.md:234, references/dotnet/data-handling.md:219 each add a one-line "For External Storage drivers that need the owning Workflow or Standalone-Activity identity, see …" cross-link. None of these expand into a multi-paragraph blurb.

No structural findings. Both gating and advisory sub-checks pass.

---

Statistics

Metric	Value
Authored / modified files	11 (4 new, 7 modified)
Inline citations	48
Citations resolved & substantively supportive	47.5 (~ 99%)
Tokens reverse-grepped against docs	~30 distinct (SDK type names, methods, option keys)
Unexplained grep-misses	1 token (StorageDriverActivityInfo in Python file, 3 usages)
Regression-pattern hits	0
Sample size (Check 4)	40 claims across 4 files
Sample match rate	39 / 40 = 97.5 %
Public Preview admonitions present	4 / 4 (canonical phrasing in 3, lightly extended in dotnet)
Check 7 link-graph edges verified	4 / 4 gating + 3 / 3 bonus
Workaround-disclosure findings (Check 6 pattern 1)	0

---

Recommended spot-fixes (no re-authoring)

1. references/python/serialization-context.md — either (a) verify the Python SDK class name and tag every StorageDriverActivityInfo reference (lines 10, 50, 78) with <!-- undocumented: source = … -->, or (b) rephrase to avoid naming the class until the Python docs (or SDK source) confirm it. This is the only substantive accuracy concern.
2. references/go/serialization-context.md:91 — replace the templated references/{your_language}/standalone-activities.md pointer with the resolved path (or with references/core/standalone-activities.md, since no Go-specific Standalone Activities page exists yet).

Neither fix touches the structure, the link graph, the Public Preview admonitions, or any citation. Both are line-level edits.