docs: codify divergence policy + add in-code breadcrumbs

Add a Divergence Policy section to docs/UPSTREAM_SYNC.md with:
- Criteria for when to diverge (data loss / malformed wire / hard UX
  failure; cosmetic issues stay on parity).
- Required workflow (file upstream issue, diverge commit prefix, add
  non-parity row, in-code breadcrumb, regression test, changelog entry).
- Review signal (sync PR title convention, budget of max 2 divergences
  per sync before escalating).

Retroactively add `# Divergence from upstream — see docs/UPSTREAM_SYNC.md`
breadcrumbs at the four divergence sites introduced in this sync:

- src/chat_sdk/thread.py `_adapter_name = adapter.name` in from_json
- src/chat_sdk/channel.py same in ChannelImpl.from_json
- src/chat_sdk/adapters/google_chat/format_converter.py to_ast()
  custom-link regex
- src/chat_sdk/adapters/google_chat/format_converter.py extract_plain_text()
  custom-link regex
- src/chat_sdk/adapters/google_chat/format_converter.py reserved-char
  fallback branch in _node_to_gchat

The placeholder-clear divergence in thread._fallback_stream already had
a full multi-line explanation; leaving that alone.

https://claude.ai/code/session_01XE1bMoQ5BjCvgi1iLGKKhG

Author: claude

docs/UPSTREAM_SYNC.md

@@ -72,6 +72,55 @@ tests. If upstream tests lock in inconsistent behavior, choose one of:
 - **Preserve parity** and document the inconsistency in the non-parity section below
 - **Intentionally diverge** and document the divergence in the non-parity section
 
+## Divergence Policy
+
+Every divergence from upstream has a cost: merge conflicts on future syncs,
+cross-SDK state drift, and a gradual slide from "port" toward "fork". Follow
+the rules below before adding one.
+
+### When to diverge
+
+1. **Default: preserve parity.** Matching upstream behavior — even buggy —
+   reduces merge conflicts and keeps cross-SDK state predictable. If the
+   behavior is cosmetic or stylistic, preserve parity and move on.
+2. **Diverge only when upstream** causes one of:
+   - **Data loss or corruption** (e.g. dropping fields on round-trip).
+   - **Malformed wire output** the platform itself mis-renders.
+   - **Hard UX failure with no workaround** (e.g. stuck loading state
+     that users can't clear).
+3. **Before diverging**, open an issue upstream
+   ([vercel/chat](https://github.com/vercel/chat/issues)) linking the bug.
+   If upstream accepts and fixes it, delete the divergence on the next sync.
+4. **Budget**: a sync PR that accumulates **more than 2 divergences** is a
+   signal — escalate to a design discussion ("is this still a port?")
+   before landing quietly.
+
+### How to land a divergence
+
+1. **Commit prefix**: use `diverge(scope): ...`, not `fix:` — `fix:` implies
+   parity with upstream's intent.
+2. **Add a row to the [Known Non-Parity](#known-non-parity-with-typescript-sdk)
+   table** with: Python behavior, TS behavior, rationale, and upstream
+   issue link (if filed).
+3. **Drop a one-line breadcrumb at the divergence site**:
+   ```python
+   # Divergence from upstream — see docs/UPSTREAM_SYNC.md
+   ```
+   So a future porter doesn't delete the code thinking it's drift.
+4. **Add a regression test** that fails if someone "fixes" the divergence
+   back to upstream's behavior. The test's docstring should cite the reason.
+5. **CHANGELOG entry** under a "Python-specific (divergence from upstream)"
+   subsection.
+
+### Review signal
+
+- **Sync PR titles**: `sync: upstream v<ver>` (not a branch name). Reviewers
+  scanning the PR list need to see "this is a sync" at a glance.
+- **Divergence commits are separate** from the sync commit. Don't bundle a
+  divergence into `sync: upstream v...`; split it into its own
+  `diverge(scope): ...` commit with the non-parity table update in the same
+  commit.
+
 ## How to Diff Upstream Changes
 
 ```bash

src/chat_sdk/adapters/google_chat/format_converter.py

@@ -42,6 +42,7 @@ def to_ast(self, gchat_text: str) -> Root:
         """
         markdown = gchat_text
 
+        # Divergence from upstream — see docs/UPSTREAM_SYNC.md.
         # Google Chat custom link syntax <url|text> -> [text](url). Must run
         # before bold/strikethrough so the `|` inside a link label isn't
         # matched by those patterns. Accepts any RFC 3986 scheme, not just
@@ -66,6 +67,7 @@ def extract_plain_text(self, text: str) -> str:
         result = re.sub(r"```[\s\S]*?```", lambda m: m.group(0).strip("`").strip(), text)
         # Inline code
         result = re.sub(r"`([^`]+)`", r"\1", result)
+        # Divergence from upstream — see docs/UPSTREAM_SYNC.md.
         # Google Chat custom link syntax: <url|text> -> text (any RFC 3986 scheme)
         result = re.sub(r"<[a-zA-Z][a-zA-Z0-9+.\-]*:[^|\s>]+\|([^>]+)>", r"\1", result)
         # Bold markers (*text*)
@@ -115,6 +117,7 @@ def _node_to_gchat(self, node: Content) -> str:
             url = node.get("url", "")
             if link_text == url:
                 return url
+            # Divergence from upstream — see docs/UPSTREAM_SYNC.md.
             # Labels containing the `|` or `>` delimiters, or a newline, can't
             # be emitted safely in <url|text> form — Google Chat (and our own
             # round-trip regex) stops at the first `>` / `|`. Fall back to

src/chat_sdk/channel.py

@@ -428,6 +428,7 @@ def from_json(
         )
         if adapter is not None:
             channel._adapter = adapter
+            # Divergence from upstream — see docs/UPSTREAM_SYNC.md.
             # Keep _adapter_name in sync with the explicit adapter so
             # to_json() doesn't serialize a stale name.
             channel._adapter_name = adapter.name

src/chat_sdk/thread.py

@@ -779,6 +779,7 @@ def from_json(
         )
         if adapter is not None:
             thread._adapter = adapter
+            # Divergence from upstream — see docs/UPSTREAM_SYNC.md.
             # Keep _adapter_name in sync with the explicit adapter so
             # to_json() doesn't serialize a stale name after rebind.
             thread._adapter_name = adapter.name