switchroom 0.21.8 → 0.21.10

package/telegram-plugin/render/render.ts

@@ -16,10 +16,11 @@
 // "HTML" }`. There is no HTML anywhere on the current outbound path (see
 // `reference/telegram-formatting-guide.md`). This renderer therefore targets
 // the ACTUAL contract: GFM markdown with the Bot API 10.1 extensions
-// documented in the formatting guide (expandable blockquote via `**> `,
-// spoiler via `||…||`, GFM pipe tables, etc). This module is NOT wired into
-// the live send path yet — that is a later increment, per the RFC's phased
-// rollout (rich rendering stays gated off by default until then).
+// documented in the formatting guide (spoiler via `||…||`, GFM pipe tables,
+// `<details>` collapsibles passed through as HTML, etc). NOTE: `**> ` is NOT
+// part of that contract — it is MarkdownV2-only syntax the rich path renders
+// as literal text (wire-verified 2026-08-13); this renderer no longer emits
+// it anywhere (see renderBlockquote).
 //
 // Round-trip note: `parse.ts` folds inline text (`PlainNode.text`,
 // `CodeNode.text`, `code-block` `text`, link `href`) into DECODED strings —
@@ -59,6 +60,14 @@ interface InlineCtx {
   inTableCell?: boolean;
 }
 
+/** Collapse any whitespace run containing a newline down to a single space.
+ *  Used for a `tg-entity` label: `![` … `]` must stay on ONE line or the
+ *  construct is not an entity any more. mdast decodes a soft line break inside
+ *  the alt text to a literal `\n`, which is exactly the case this flattens. */
+function collapseLabelBreaks(label: string): string {
+  return label.replace(/[ \t]*\r?\n[ \t\r\n]*/g, " ");
+}
+
 function renderInline(node: Inline, ctx: InlineCtx = {}): string {
   switch (node.type) {
     case "plain":
@@ -91,6 +100,25 @@ function renderInline(node: Inline, ctx: InlineCtx = {}): string {
       // Escape the href so a literal `)` in the URL can't terminate the
       // destination early and break the link (F3).
       return `[${renderInlineChildren(node.children, ctx)}](${escapeLinkHref(node.href)})`;
+    case "tg-entity":
+      // `![label](tg://time?unix=…&format=…)` / `![](tg://emoji?id=…)`.
+      // The label is PROSE (the alternative text Telegram shows when it can't
+      // render the entity), so it is escaped exactly like a `plain` node —
+      // without that, a label containing `]` or a formatting delimiter
+      // (`![see [22:45]](tg://time?…)`) closes the label early and smuggles
+      // raw bracket syntax past the renderer. A newline inside the label would
+      // split the construct across lines, so runs of whitespace spanning one
+      // are collapsed to a single space first. The href gets the same
+      // `escapeLinkHref` treatment a link's does (a no-op for the paren-free
+      // `tg:` URLs in practice, load-bearing if one ever carries a `)`).
+      return `![${escapeMarkdown(collapseLabelBreaks(node.label))}](${escapeLinkHref(node.href)})`;
+    case "raw":
+      // Verbatim wire passthrough — the source bytes ARE the wire syntax
+      // (footnote reference markers `[^1]` / definition lines `[^1]: …`,
+      // which Telegram's rich parser renders natively; escapeMarkdown would
+      // escape their `[`/`]` and break the construct — the exact bug this
+      // node type exists to prevent).
+      return node.text;
     default: {
       // Exhaustiveness guard — the IR union is closed; a new variant must be
       // handled above rather than silently dropped.
@@ -118,17 +146,20 @@ function prefixLines(text: string, prefix: string): string {
 
 function renderBlockquote(node: BlockquoteNode): string {
   const inner = renderBlocks(node.children);
-  // Bot API 10.1 expandable blockquote: `**> ` on the first quoted line.
-  // Plain blockquote: `> ` on every line.
-  if (node.expandable) {
-    const lines = inner.split("\n");
-    return lines
-      .map((line, i) => {
-        const marker = i === 0 ? "**> " : "> ";
-        return line.length > 0 ? `${marker}${line}` : marker.trimEnd();
-      })
-      .join("\n");
-  }
+  // Always a plain `> ` blockquote — including for `expandable: true` nodes.
+  //
+  // This renderer USED to emit `**> ` on the first line of an expandable
+  // quote, believing it to be the Bot API 10.1 expandable-blockquote marker.
+  // That belief was falsified by raw sendRichMessage wire probes (2026-08-13):
+  // `**>` is MarkdownV2 syntax; the rich markdown path renders it as a LITERAL
+  // `**> …` paragraph followed by a detached plain quote. The `expandable`
+  // flag is retained on the IR (parse.ts still repairs legacy `**>` input into
+  // a real blockquote instead of letting the literal `**>` reach the wire),
+  // but it is NOT a distinct wire style — the faithful degradation is a plain
+  // quote, which shows the full content. An author who wants a genuine
+  // collapsible writes `<details><summary>…</summary>…</details>`, which the
+  // rich path renders natively (typed `details` node, wire-verified) and which
+  // passes through this pipeline verbatim.
   return prefixLines(inner, "> ");
 }
 
@@ -299,6 +330,13 @@ export const SUPPORTED_INLINE = [
   "highlight",
   "code",
   "link",
+  // `![…](tg://time?…)` / `![…](tg://emoji?id=…)` — the two inline `tg:`
+  // entities in Telegram's Rich Markdown grammar. Emitted verbatim (label and
+  // href re-escaped); any OTHER image url stays a `plain` node.
+  "tg-entity",
+  // Verbatim passthrough for constructs whose SOURCE bytes are the wire syntax
+  // (footnote markers/definitions). Never escaped, never rewritten.
+  "raw",
 ] as const;
 
 export const SUPPORTED_BLOCK = [

package/telegram-plugin/render/unsupported-token-guard.ts

@@ -3,44 +3,55 @@
 //
 // ── Root cause ───────────────────────────────────────────────────────────
 // Assistant replies are composed by a model that habitually emits constructs
-// from OTHER surfaces (GitHub / Obsidian / LaTeX): caret highlight/superscript
-// `^…^`, footnote markers `[^1]`, and HTML `<details><summary>` collapsibles.
-// None of these are part of Telegram's rich markdown; they degrade to literal
-// carets, stray `[^1]`, and raw `<details>` tags on the reader's screen — the
-// worst kind of consistency failure (a broken glyph in chat). The resident
-// floor card tells the model not to emit them, but prompt discipline is not a
-// guarantee. This guard makes the repair deterministic at send time.
+// from OTHER surfaces (GitHub / Obsidian / LaTeX). Most of them turn out to be
+// natively supported by Telegram's rich markdown path (wire-verified
+// 2026-08-13 by sending raw `sendRichMessage` probes and reading back the
+// echoed `rich_message.blocks`):
+//   • `<details open><summary>S</summary>…</details>` → a real typed
+//     `details` node (native collapsible) — SUPPORTED, must pass through.
+//   • `$x^2+y^2$` → a `mathematical_expression` node — SUPPORTED (and
+//     protected from the sibling guards via `splitProtectedSegments`'s
+//     compact-math-span rule; see code-segments.ts).
+//   • footnotes `claim[^1]` + `[^1]: body` → full superscript/anchor/
+//     reference_link/footer machinery — SUPPORTED, must pass through.
+//   • `<sub>`/`<sup>`/`<u>`, `<aside>…<cite>…</cite></aside>`, `tg://time`
+//     links, `- [ ]` task lists — all SUPPORTED, never touched here.
+// (An earlier revision of this guard "repaired" `<details>` into a `**> `
+// expandable blockquote and deleted footnote reference markers. Both repairs
+// were built on a false belief: `**>` is MarkdownV2 syntax that the rich
+// markdown path renders as LITERAL `**>` paragraph text — the probe proved the
+// conversion turned a SUPPORTED construct into an UNSUPPORTED one. That logic
+// is deleted, not gated.)
+//
+// What genuinely does NOT render and still needs repair: the caret
+// highlight/superscript shorthand `^…^`. Telegram's rich markdown has no caret
+// syntax — the carets render literally on the reader's screen. The resident
+// floor card tells the model to use `<sup>…</sup>` instead, but prompt
+// discipline is not a guarantee; this guard makes the repair deterministic at
+// send time.
 //
 // ── What it repairs (deterministic, pure string transform) ─────────────────
-//   • `<details><summary>Title</summary>body</details>` → a Telegram EXPANDABLE
-//     blockquote (`**> Title` first line + `> …` continuation) — the native
-//     equivalent of a collapsible. `<details>` without a `<summary>` folds the
-//     whole body into an expandable blockquote. Any orphan `<details>` /
-//     `</details>` / `<summary>` tags left over are stripped.
-//   • `^highlight^` / `x^2^` caret pairs → the inner text, carets removed
-//     (Telegram has no highlight/superscript; the carets render literally).
-//   • Footnote reference markers `[^id]` → removed (Telegram has no footnotes).
-//     A footnote DEFINITION line `[^id]: …` is left alone (the `]:` lookahead).
+//   • `^highlight^` / `x^2^` caret pairs → the inner text, carets removed.
 //
 // ── What it deliberately does NOT touch ────────────────────────────────────
-//   • `$…$` math: already neutralised deterministically upstream by
-//     `guardDollarMath` (it backslash-escapes `$` so the pair can never typeset
-//     as math — the reader sees literal `$`). Re-processing `$` here would
-//     double-process and risk corrupting currency prose, so this guard leaves
-//     `$` untouched by design. Math repair is COVERED, just in the sibling guard.
+//   • `$…$` math: a compact math span is PROTECTED upstream (a `code: true`
+//     segment from `splitProtectedSegments`), and accidental currency `$` is
+//     owned by `guardDollarMath` (disjoint char set).
 //   • `~sub~` tilde pairs: the strikethrough/tilde trigger is owned by
 //     `guardAccidentalInlinePairs` (disjoint char set). This guard never
 //     inspects or inserts `~`.
 //   • `__underline__`: renders as BOLD in Telegram — legible, not broken — so it
 //     is left as-is (the floor card asks the model to avoid it, but there is no
 //     glyph-level failure to repair).
+//   • footnote markers `[^id]` / definitions `[^id]: …`: natively supported,
+//     pass through verbatim. (The caret regex below can never touch them: the
+//     `]` / `:` break the alphanumeric-only inner run.)
 //
-// Code spans / fenced blocks / link destinations / table rows are emitted
-// verbatim (shared `splitProtectedSegments`). A strict no-op for any body
-// without one of these tokens, and idempotent (running twice is a no-op the
-// second time — a repaired blockquote contains no `<details>`, a stripped caret
-// pair contains no `^`). Safe to compose once per send alongside the #3252
-// accidental-formatting guards.
+// Code spans / fenced blocks / link destinations / math spans / table rows are
+// emitted verbatim (shared `splitProtectedSegments`). A strict no-op for any
+// body without a caret pair, and idempotent (a stripped caret pair contains no
+// `^`). Safe to compose once per send alongside the #3252 accidental-formatting
+// guards.
 
 import { splitProtectedSegments } from "./code-segments.js";
 
@@ -56,69 +67,23 @@ import { splitProtectedSegments } from "./code-segments.js";
  *  permissive inner run the first two carets of `a^2+b^2=c^2` pair up (`^2+b^`)
  *  and get stripped, mangling the math; requiring the inner run to be pure
  *  alphanumerics means `^2+b^` never matches (the `+` breaks the run), so
- *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. */
+ *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. It also keeps
+ *  the guard off footnote markers `[^1]` (the `]` breaks the run). */
 const CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
 
-/** Footnote reference marker `[^id]` where the id is a short alphanumeric run
- *  (`[^1]`, `[^note]`, `[^ref]`) NOT immediately followed by `:` (which would
- *  make it a footnote DEFINITION line we leave intact). Removed entirely.
- *  Requiring the id to be 1–10 ALPHANUMERIC chars keeps this off regex-ish
- *  literals like `[^/]`, `[^\s]`, `[^-a-z]`, whose bodies contain punctuation
- *  and so never match. In-prose subscript-ish `array[^i]` outside a code span
- *  is a rare theoretical false positive (an `i` id matches); code spans are
- *  masked upstream by splitProtectedSegments so real code is safe, and prose
- *  that writes a literal `[^i]` reads as footnote noise anyway. */
-const FOOTNOTE_MARKER = /\[\^[A-Za-z0-9]{1,10}\](?!:)/g;
-
-/** `<details>…</details>` with an optional leading `<summary>…</summary>`.
- *  Dot-all via `[\s\S]`; non-greedy so adjacent blocks don't merge. */
-const DETAILS_BLOCK =
-  /<details[^>]*>\s*(?:<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/gi;
-
-/** Orphan collapsible tags left after DETAILS_BLOCK (malformed / unpaired). */
-const ORPHAN_TAGS = /<\/?(?:details|summary)[^>]*>/gi;
-
-/** Fold `title` + `body` into a Telegram expandable blockquote: the first
- *  emitted line carries the `**> ` marker (switchroom's expandable-blockquote
- *  encoding — see parse.ts), every subsequent line a plain `> `. */
-function toExpandableBlockquote(title: string, body: string): string {
-  const lines: string[] = [];
-  const t = title.trim();
-  if (t) lines.push(t);
-  for (const raw of body.split("\n")) {
-    const line = raw.trimEnd();
-    // Collapse leading/trailing blank lines but keep interior structure.
-    if (line.trim() === "" && lines.length === 0) continue;
-    lines.push(line);
-  }
-  // Trim trailing blanks.
-  while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
-  if (lines.length === 0) return "";
-  return lines
-    .map((line, i) => (i === 0 ? `**> ${line}` : `> ${line}`))
-    .join("\n");
-}
-
 /** Repair unsupported tokens in a single PROSE segment. */
 function repairProse(text: string): string {
-  let out = text;
-  out = out.replace(DETAILS_BLOCK, (_m, summary: string | undefined, body: string) =>
-    toExpandableBlockquote(summary ?? "", body ?? ""),
-  );
-  out = out.replace(ORPHAN_TAGS, "");
-  out = out.replace(CARET_PAIR, (_m, inner: string) => inner);
-  out = out.replace(FOOTNOTE_MARKER, "");
-  return out;
+  return text.replace(CARET_PAIR, (_m, inner: string) => inner);
 }
 
 /**
- * Neutralise Telegram-unrenderable tokens (`<details>`, `^…^`, `[^1]`) on the
- * FINAL rendered rich-markdown string. Code / links / tables are verbatim.
+ * Neutralise Telegram-unrenderable caret pairs (`^…^`) on the FINAL rendered
+ * rich-markdown string. Code / links / math spans / tables are verbatim.
  * Deterministic, idempotent, and a strict no-op absent any target token.
  */
 export function guardUnsupportedTokens(text: string): string {
-  // Cheap pre-check: nothing to do unless a target trigger char is present.
-  if (!/[\^]|<details|<\/details|<summary/i.test(text)) return text;
+  // Cheap pre-check: nothing to do unless a caret is present at all.
+  if (!text.includes("^")) return text;
   return splitProtectedSegments(text)
     .map((seg) => (seg.code ? seg.text : repairProse(seg.text)))
     .join("");

package/telegram-plugin/rich-send.ts

@@ -54,16 +54,31 @@ export interface InputRichMessageMarkdown {
  * guards is disjoint in the characters it inspects AND the characters it
  * inserts (`\_ \* \> \. \~ \=\= \|\|` vs `\$`), so no other insertion can
  * create or destroy a signal for a sibling. Verified by composition tests.
+ *
+ * Intentional inline math (`$x^2+y^2$`, a native Telegram construct) is
+ * PROTECTED from every sub-guard: `splitProtectedSegments` treats a compact
+ * non-currency `$…$` span like a code span (see code-segments.ts), so the
+ * dollar guard neither counts nor escapes its `$` and the emphasis/caret
+ * guards never rewrite its interior.
  */
 export function guardAccidentalFormatting(markdown: string): string {
   let out = markdown
-  // Repair Telegram-unrenderable tokens FIRST: `<details>` folds into a `**> `
-  // expandable blockquote whose `> `-with-space lines are invisible to the
-  // block-construct guard (which only escapes space-LESS `>digit`/`>=`), and
-  // `**> ` is the exact marker switchroom's own render path emits — so the
-  // downstream emphasis/block guards treat it identically to a native
-  // expandable quote. Caret/footnote removal inserts no trigger char for any
-  // sibling guard, so this pass neither creates nor destroys their signals.
+  // Repair Telegram-unrenderable tokens FIRST. This pass now strips ONLY caret
+  // pairs (`^x^` → `x`): removing a `^` inserts no trigger char for any
+  // sibling guard, so it neither creates nor destroys their signals.
+  //
+  // What this pass deliberately NO LONGER does (wire-verified 2026-08-13 by
+  // raw `sendRichMessage` probes): it used to fold `<details>` into a `**> `
+  // "expandable blockquote" and delete footnote markers `[^1]`. Both beliefs
+  // were false — `<details><summary>` and footnotes are NATIVE rich-markdown
+  // constructs (typed `details` / footnote nodes on the wire), while `**>` is
+  // MarkdownV2-only syntax the rich path renders as LITERAL `**>` text. The
+  // conversion destroyed a supported construct to emit an unsupported one, so
+  // it is deleted. `<details>`, footnotes, `<sub>`/`<sup>`/`<u>`, `<aside>`,
+  // `tg://` links and task lists all pass through every guard untouched: none
+  // of `< > [ ] : /` is a trigger char for the emphasis / heading /
+  // block-construct / inline-pair / dollar guards ('composition' tests cover
+  // this interaction).
   out = guardUnsupportedTokens(out)
   out = guardAccidentalEmphasis(out)
   out = guardAccidentalHeading(out)

package/telegram-plugin/shared/bot-runtime.ts

@@ -251,8 +251,9 @@ export function installTgPostLogger(bot: Bot): void {
  * call site, `ctx.*` sugar, `lockedBot`, or `bot.api.raw`, so it closes the
  * whole bypass class deterministically.
  *
- * Payload shape (verified against grammy 1.44.0 `out/core/api.js`, the pinned
- * lockfile version):
+ * Payload shape (verified against grammy 1.45.1 `out/core/api.js`, the pinned
+ * lockfile version — byte-identical to the 1.44.0 shape this was originally
+ * written against, re-checked on the 1.45.1 bump):
  *   - `sendRichMessage(chat_id, rich_message, ...)` → raw payload
  *     `{ chat_id, rich_message: { markdown }, ... }`
  *   - `editMessageText(chat_id, message_id, arg, ...)` → raw payload

package/telegram-plugin/telegraph.ts

@@ -193,10 +193,12 @@ export async function createTelegraphPage(
 }
 
 /**
- * A blockquote line: a plain `> ` marker OR the expandable-blockquote opener
- * `**> ` (Bot API 10.1 syntax the switchroom render path emits on the first
- * line of an expandable quote — see `render/render.ts` and
- * `reference/telegram-formatting-guide.md`). Telegra.ph has no collapsible
+ * A blockquote line: a plain `> ` marker OR the LEGACY expandable-blockquote
+ * opener `**> ` (a switchroom encoding once believed to be Bot API 10.1
+ * syntax; wire probes 2026-08-13 showed the rich path renders `**>` as
+ * literal text, so `render/render.ts` no longer emits it — but legacy agent
+ * output still contains it and it must be tolerated on input here).
+ * Telegra.ph has no collapsible
  * blockquote tag, so an expandable quote degrades to a normal `<blockquote>`;
  * the `**` prefix must still be recognised and stripped here, else the
  * unterminated `**` renders as literal `**>` text and the `>` continuation

package/telegram-plugin/tests/grammy-rich-message-types.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Compile-time contract for the grammy 1.44.0 → 1.45.1 bump
+ * (`@grammyjs/types` 3.28.0 → 4.0.0).
+ *
+ * Why this file exists
+ * --------------------
+ * 4.0.0 turned `InputRichMessage` from a plain interface into a GENERIC one:
+ *
+ *   3.28.0  `export interface InputRichMessage {`            (rich.d.ts:280)
+ *   4.0.0   `export interface InputRichMessage<F> {`         (rich.d.ts:283)
+ *
+ * `F` is the file-payload type threaded through the new Bot API 10.2 `blocks`
+ * / `media` fields. Switchroom never uses either — every outbound message is
+ * the plain `{ markdown }` shape (`rich-send.ts:96`), and the plugin defines
+ * its OWN local `InputRichMessageMarkdown` (`rich-send.ts:28`) rather than
+ * importing grammy's. So the bump is only safe as long as a bare
+ * `{ markdown: string }` literal still satisfies the generic parameter at
+ * every call site.
+ *
+ * That invariant is invisible to the rest of the suite for two reasons, and
+ * both are why this test spends ~1s on a real compile instead of asserting on
+ * runtime values:
+ *
+ *   1. Every send in the regression suite is MOCKED — no mock can notice that
+ *      a payload stopped typechecking.
+ *   2. The repo's `tsc --noEmit` does NOT cover this directory. The root
+ *      `tsconfig.json` `include` is `["src/**\/*.ts", "bin/**\/*.ts",
+ *      "scripts/**\/*.ts"]` — `telegram-plugin/` is absent, so a type error
+ *      here is invisible to `npm run lint` (verified empirically: a deliberate
+ *      `const x: number = "s"` in `rich-send.ts` leaves `tsc --noEmit` at exit
+ *      0). A plain `.ts` fixture would therefore be a NO-OP as a guard.
+ *
+ * So the check has to run the compiler itself. The negative controls below are
+ * load-bearing: if the harness ever silently stopped compiling (bad fixture
+ * path, unresolved `grammy`, swallowed diagnostics), the "must fail" cases
+ * would go green and this file goes red — it cannot rot into a vacuous pass.
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import ts from 'typescript'
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Fixtures must live INSIDE the repo tree: they `import 'grammy'`, and module
+// resolution walks up from the file to the hoisted root `node_modules`. A
+// fixture in `os.tmpdir()` would fail to resolve grammy and every case would
+// report a misleading "cannot find module" instead of the real answer.
+const fixtureDir = mkdtempSync(join(here, 'grammy-types-fixture-'))
+afterAll(() => rmSync(fixtureDir, { recursive: true, force: true }))
+
+/** Mirrors the compiler settings the plugin is actually authored against. */
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  strict: true,
+  // Matches the root tsconfig: we are asserting on OUR call shapes, not
+  // auditing grammy's own .d.ts files.
+  skipLibCheck: true,
+  noEmit: true,
+}
+
+/**
+ * Typecheck one fixture source and return its syntactic + semantic errors,
+ * formatted `TSxxxx: message`. Empty array means "compiles clean".
+ */
+function typecheck(name: string, source: string): string[] {
+  const file = resolve(fixtureDir, `${name}.ts`)
+  writeFileSync(file, source)
+  const program = ts.createProgram([file], COMPILER_OPTIONS)
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file?.fileName === file.split('\\').join('/'))
+    .map((d) => `TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`)
+}
+
+describe('grammy rich-message input still accepts the plain { markdown } shape', () => {
+  it('accepts a bare { markdown } literal on sendRichMessage and editMessageText', () => {
+    expect(
+      typecheck(
+        'plain-literal',
+        `
+        import type { Bot } from 'grammy'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.sendRichMessage(1, { markdown: 'hi' })
+          await bot.api.editMessageText(1, 2, { markdown: 'hi' })
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  it("accepts the production helper's return type (rich-send.ts richMessage())", () => {
+    // The real seam: `richMessage()` returns the plugin's OWN local
+    // `InputRichMessageMarkdown`, which must stay structurally assignable to
+    // grammy's generic parameter. This is the assertion that would break if a
+    // future @grammyjs/types made `blocks`/`media` mandatory or constrained `F`.
+    expect(
+      typecheck(
+        'production-helper',
+        `
+        import type { Bot } from 'grammy'
+        import { richMessage } from '${join(here, '..', 'rich-send.js').split('\\').join('/')}'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.sendRichMessage(1, richMessage('hi'))
+          await bot.api.editMessageText(1, 2, richMessage('hi'))
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  it('still accepts a { markdown } payload through bot.api.raw', () => {
+    // `installRichMarkdownGuard` (shared/bot-runtime.ts) inspects the RAW
+    // payload `{ chat_id, rich_message: { markdown } }`, so pin that shape too.
+    expect(
+      typecheck(
+        'raw-payload',
+        `
+        import type { Bot } from 'grammy'
+        declare const bot: Bot
+        export async function send(): Promise<void> {
+          await bot.api.raw.sendRichMessage({ chat_id: 1, rich_message: { markdown: 'hi' } })
+        }
+        `,
+      ),
+    ).toEqual([])
+  })
+
+  // ── Negative controls: prove the harness has teeth ──────────────────────
+  // Without these, every assertion above would pass just as happily against a
+  // harness that had silently stopped compiling anything at all.
+
+  it('NEGATIVE CONTROL: rejects a wrongly-typed markdown field', () => {
+    const errors = typecheck(
+      'wrong-type',
+      `
+      import type { Bot } from 'grammy'
+      declare const bot: Bot
+      export async function send(): Promise<void> {
+        await bot.api.sendRichMessage(1, { markdown: 123 })
+      }
+      `,
+    )
+    expect(errors.join('\n')).toContain('TS2322')
+  })
+
+  it('NEGATIVE CONTROL: rejects an unknown field on the rich-message literal', () => {
+    const errors = typecheck(
+      'unknown-field',
+      `
+      import type { Bot } from 'grammy'
+      declare const bot: Bot
+      export async function send(): Promise<void> {
+        await bot.api.sendRichMessage(1, { markdwon: 'typo' })
+      }
+      `,
+    )
+    expect(errors.length).toBeGreaterThan(0)
+  })
+})
+
+describe('grammy supply-chain pin', () => {
+  // Assert on `bun.lock` rather than the resolved package: grammy's `exports`
+  // map deliberately hides `./package.json`, and the lockfile is the artifact
+  // CI actually installs from (`bun install --frozen-lockfile`), so it is both
+  // reachable and the more honest source of truth for what ships.
+  const lock = readFileSync(resolve(here, '..', '..', 'bun.lock'), 'utf8')
+
+  /** Pull the resolved version bun.lock pins for a package. */
+  function lockedVersion(pkg: string): string {
+    const escaped = pkg.replace('/', '\\/')
+    const m = new RegExp(`"${escaped}": \\["${escaped}@(\\d+\\.\\d+\\.\\d+)"`).exec(lock)
+    if (!m) throw new Error(`no bun.lock pin found for ${pkg}`)
+    return m[1]
+  }
+
+  // These assert a FLOOR, not an exact version: a later 1.46/5.x bump is a
+  // legitimate change and must not go red here for no substantive reason. What
+  // must never happen silently is a slide BACK below the floor — that would
+  // return @grammyjs/types to 3.28.0 and drop the Bot API 10.2 surface this
+  // bump exists to unlock, while every assertion above stayed green (the plain
+  // `{ markdown }` shape compiles under both).
+
+  it('keeps grammy at or above 1.45 (the floor that ships @grammyjs/types 4.x)', () => {
+    const [major, minor] = lockedVersion('grammy').split('.').map(Number)
+    expect(major).toBe(1)
+    expect(minor).toBeGreaterThanOrEqual(45)
+  })
+
+  it('keeps @grammyjs/types at or above the 4.x major grammy 1.45 depends on', () => {
+    const [major] = lockedVersion('@grammyjs/types').split('.').map(Number)
+    expect(major).toBeGreaterThanOrEqual(4)
+  })
+})

package/telegram-plugin/tests/render/dollar-math-guard.test.ts

@@ -160,3 +160,46 @@ describe("guardDollarMath — link / table awareness (findings 1 & 3)", () => {
     expect(out).not.toMatch(/(?<!\\)\$/);
   });
 });
+
+describe("guardDollarMath — intentional math spans are exempt (wire-verified 2026-08-13)", () => {
+  it("never escapes a compact `$…$` math span", () => {
+    // Telegram renders `$x^2+y^2$` as a native mathematical_expression node;
+    // escaping it destroys a SUPPORTED construct. On the pre-fix guard this
+    // input came back as `inline \$x^2+y^2\$ done`.
+    const s = "inline $x^2+y^2$ done";
+    expect(guardDollarMath(s)).toBe(s);
+  });
+
+  it("math span dollars do not count toward the 2+ arming threshold", () => {
+    // Only ONE prose `$` outside the math span → can never pair → untouched.
+    const s = "solve $x^2+y^2$ for the $BUDGET case";
+    expect(guardDollarMath(s)).toBe(s);
+  });
+
+  it("still escapes currency in the SAME message as an exempt math span", () => {
+    const out = guardDollarMath("sum $x^2+y^2$ costs $5 and $10");
+    expect(out).toContain("$x^2+y^2$");
+    expect(out).toContain("\\$5");
+    expect(out).toContain("\\$10");
+  });
+
+  it("a currency-shaped compact pair (`$5M-$10M`) is NOT treated as math", () => {
+    // The `$5M-$` inner run is digits/magnitude punctuation only — two
+    // adjacent amounts, the exact #3252 accident. Must still be escaped.
+    const out = guardDollarMath("the range is $5M-$10M this year");
+    expect(out).not.toMatch(/(?<!\\)\$/);
+  });
+
+  it("spaced `$…$` spans are NOT exempt (indistinguishable from currency prose)", () => {
+    // Documented residual: `$a + b$` cannot be told apart from two stray
+    // currency signs, so when a currency signal arms the guard it is escaped
+    // (renders as literal text — legible, not broken).
+    const out = guardDollarMath("we know $a + b$ plus $5 fees");
+    expect(out).not.toMatch(/(?<!\\)\$/);
+  });
+
+  it("is idempotent with a math span present", () => {
+    const once = guardDollarMath("sum $x^2+y^2$ costs $5 and $10");
+    expect(guardDollarMath(once)).toBe(once);
+  });
+});