switchroom 0.17.6 → 0.18.3

package/telegram-plugin/memory-legibility.ts

@@ -0,0 +1,217 @@
+/**
+ * Sparse, chat-legible memory surface — hindsight Phase 4 (#2849).
+ *
+ * When the interactive `claude` session materially changes what it
+ * remembers during a turn — stores a new standing directive, or
+ * invalidates / demotes an existing memory — this module surfaces ONE
+ * terse line in the ORIGINATING Telegram chat/topic:
+ *
+ *   📌 <i>remembered:</i> "Always prefer TypeScript for this user"
+ *   ✂️ <i>forgot:</i> superseded deploy runbook
+ *
+ * Why so sparse: the `remember-across-sessions` job spec lists
+ * "regurgitating old facts unprompted just to prove it remembered" as a
+ * top anti-pattern. A per-turn line would *become* that anti-pattern, so
+ * this surface fires ONLY on a genuine store/correct — never on ordinary
+ * recall, and never on routine consolidation. Detection is a
+ * deterministic tool-call observation (no model call, no polling): we
+ * watch the main-agent turn stream for the specific hindsight memory
+ * tools that represent a material change.
+ *
+ * Design notes / references:
+ *   - RFC Phase 4: `reference/rfcs/hindsight-synthesis-layers.md`
+ *   - Job spec: `reference/jobs/remember-across-sessions.md`
+ *   - The `consolidation.completed` webhook the RFC names as the poll-free
+ *     driver for the "updated what I know about Y" side does NOT exist in
+ *     the pinned hindsight image (v0.8.4) — it is RFC-only. This v1 ships
+ *     the tool-observation path; the webhook stays a follow-up.
+ *
+ * Reuse: `classifyMemoryToolCall` / `detectMemoryLegibilityEvent` are the
+ * single, reusable "did a directive-create / invalidate happen in this
+ * turn?" primitive on the TypeScript gateway side. Phase 3 Stage B (#2848)
+ * runs as a vendored Python hook (`recall.py`) and CANNOT import this TS
+ * module — it mirrors the same hindsight tool-name matching independently.
+ * Keep the two in sync by hand when the tool surface changes.
+ */
+
+import { stripMarkdown, truncate } from './card-format.js'
+
+/** ON by default; an operator opts out with SWITCHROOM_MEMORY_LEGIBILITY=0.
+ *  Mirrors the SWITCHROOM_WORKER_ACTIVITY_FEED convention (only the literal
+ *  string '0' disables; unset / anything else → enabled). */
+export function isMemoryLegibilityEnabled(envVal: string | undefined): boolean {
+  return envVal !== '0'
+}
+
+/**
+ * The material memory operations we surface. Deliberately narrow — an
+ * ordinary `recall` / `reflect` / benign `update_memory` (a non-demote
+ * edit) is NOT material and returns null from the classifier.
+ */
+export type MemoryToolClass = 'directive-create' | 'memory-invalidate'
+
+/** The two hindsight tools that represent a material store / correct.
+ *  Fully-qualified names as they appear in the turn stream (`ev.toolName`). */
+export const CREATE_DIRECTIVE_TOOL = 'mcp__hindsight__create_directive'
+export const INVALIDATE_MEMORY_TOOL = 'mcp__hindsight__invalidate_memory'
+/** The demote path (`switchroom memory demote`) adds this client-side tag
+ *  via the `update_memory` tool; that specific tagging is the "forgot"
+ *  signal, whereas a plain `update_memory` edit is not material. */
+export const UPDATE_MEMORY_TOOL = 'mcp__hindsight__update_memory'
+export const DEMOTE_FROM_RECALL_MARKER = 'demote-from-recall'
+
+export type MemoryLegibilityKind = 'remembered' | 'forgot'
+
+export interface MemoryLegibilityEvent {
+  kind: MemoryLegibilityKind
+  /** Best-effort human detail (directive body / invalidate reason). May be
+   *  empty when the tool carries no legible detail — the render then falls
+   *  back to a bare "forgot a memory" line. Raw (unescaped, unstripped);
+   *  `renderMemoryLegibilityLine` does the cleanup. */
+  detail: string
+}
+
+function asString(v: unknown): string {
+  return typeof v === 'string' ? v : ''
+}
+
+/** True when an `update_memory` call's tags carry the demote-from-recall
+ *  marker — the only shape of `update_memory` that is a material correction.
+ *  Bracket- and case-tolerant (`[demote-from-recall]` / `demote-from-recall`). */
+function hasDemoteTag(input: Record<string, unknown> | undefined): boolean {
+  if (input == null) return false
+  const pools: unknown[] = []
+  for (const key of ['add_tags', 'tags']) {
+    const val = input[key]
+    if (Array.isArray(val)) pools.push(...val)
+    else if (typeof val === 'string') pools.push(val)
+  }
+  return pools.some(
+    (t) => typeof t === 'string' && t.toLowerCase().includes(DEMOTE_FROM_RECALL_MARKER),
+  )
+}
+
+/**
+ * Classify a single tool call as a material memory operation, or null if
+ * it isn't one. This is the reusable detection primitive: it answers "did a
+ * directive-create / invalidate happen in this turn?" with no rendering
+ * concern. #2848 Stage B (the vendored Python `recall.py` hook) mirrors this
+ * matching independently — it cannot import this TS module.
+ */
+export function classifyMemoryToolCall(
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+): MemoryToolClass | null {
+  if (toolName === CREATE_DIRECTIVE_TOOL) return 'directive-create'
+  if (toolName === INVALIDATE_MEMORY_TOOL) return 'memory-invalidate'
+  // `update_memory` is material ONLY when it applies the demote-from-recall
+  // tag; any other edit is routine and must not surface a line.
+  if (toolName === UPDATE_MEMORY_TOOL && hasDemoteTag(input)) return 'memory-invalidate'
+  return null
+}
+
+/**
+ * Detect a surfaceable memory-legibility event from one tool call, or null.
+ * Pure — no I/O. Extracts the best-available human detail from the tool
+ * input so the caller can render + route it.
+ */
+export function detectMemoryLegibilityEvent(
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+): MemoryLegibilityEvent | null {
+  const klass = classifyMemoryToolCall(toolName, input)
+  if (klass == null) return null
+  if (klass === 'directive-create') {
+    // The live server requires `content` (directive body); the profile
+    // guidance example writes `create_directive(text)`, so tolerate both,
+    // then fall back to the directive `name`.
+    const detail =
+      asString(input?.content).trim() ||
+      asString(input?.text).trim() ||
+      asString(input?.name).trim()
+    return { kind: 'remembered', detail }
+  }
+  // memory-invalidate: prefer a human `reason`; the opaque memory_id is not
+  // user-legible, so omit it and let the render use the bare fallback.
+  const detail = asString(input?.reason).trim()
+  return { kind: 'forgot', detail }
+}
+
+/**
+ * Confirm-before-legibility stager (Fix 1.3, #2903).
+ *
+ * A material memory op is detected on the `tool_use` event, but the write is
+ * not yet confirmed — the hindsight `tools/call` can still fail (engine down,
+ * `isError` envelope) and return an error `tool_result`. Sending the 📌/✂️ line
+ * on the tool_use would claim "remembered" for a write that then failed.
+ *
+ * This stager holds detected events keyed by `toolUseId`. `confirm` returns the
+ * event to send ONLY on a successful result; a failed result (`isError`) drops
+ * it and returns null. Pure and I/O-free so the send/no-send decision is unit-
+ * testable independent of the gateway's Telegram plumbing.
+ *
+ * `M` is caller-side routing metadata (chat/thread) carried opaquely.
+ */
+export class MemoryLegibilityStager<M> {
+  private pending = new Map<string, { event: MemoryLegibilityEvent; meta: M }>()
+  /** Bound the map so a turn that never emits a matching tool_result (crash
+   *  mid-tool) can't leak entries unboundedly. */
+  constructor(private readonly cap = 256) {}
+
+  /** Stage a detected event awaiting result confirmation. */
+  stage(toolUseId: string, event: MemoryLegibilityEvent, meta: M): void {
+    if (this.pending.size >= this.cap) {
+      const oldest = this.pending.keys().next().value
+      if (oldest != null) this.pending.delete(oldest)
+    }
+    this.pending.set(toolUseId, { event, meta })
+  }
+
+  /**
+   * Resolve a staged event on its matching tool_result. Returns the event +
+   * meta to send on CONFIRMED success; returns null when the write errored,
+   * when nothing was staged for this id, or when the id is empty. Always
+   * consumes the staged entry.
+   */
+  confirm(
+    toolUseId: string | null | undefined,
+    isError: boolean | undefined,
+  ): { event: MemoryLegibilityEvent; meta: M } | null {
+    if (toolUseId == null || toolUseId.length === 0) return null
+    const staged = this.pending.get(toolUseId)
+    if (staged == null) return null
+    this.pending.delete(toolUseId)
+    if (isError === true) return null
+    return staged
+  }
+
+  /** Test/introspection helper: number of currently-staged events. */
+  get size(): number {
+    return this.pending.size
+  }
+}
+
+/** HTML-escape for parse_mode:'HTML' (escape the 3 entity-significant chars). */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** Max chars of directive/reason detail shown on the one-liner. */
+const DETAIL_MAX = 160
+
+/**
+ * Render the terse one-line surface (Telegram HTML). Callers send this as a
+ * real `sendMessage` (not a draft/reaction) so it's observable + durable.
+ *
+ *   📌 <i>remembered:</i> "<directive, cleaned + truncated>"
+ *   ✂️ <i>forgot:</i> <reason>            (or "✂️ <i>forgot a memory.</i>")
+ */
+export function renderMemoryLegibilityLine(ev: MemoryLegibilityEvent): string {
+  const clean = truncate(stripMarkdown(ev.detail).replace(/\s+/g, ' ').trim(), DETAIL_MAX)
+  if (ev.kind === 'remembered') {
+    if (clean.length === 0) return `📌 <i>remembered a new directive.</i>`
+    return `📌 <i>remembered:</i> "${escapeHtml(clean)}"`
+  }
+  if (clean.length === 0) return `✂️ <i>forgot a memory.</i>`
+  return `✂️ <i>forgot:</i> ${escapeHtml(clean)}`
+}

package/telegram-plugin/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"3.2.4","results":[[":tests/worker-activity-feed.test.ts",{"duration":604.6399409999995,"failed":true}]]}

package/telegram-plugin/package.json

@@ -33,8 +33,14 @@
     "@secretlint/types": "^12.2.0",
     "@xterm/headless": "^6.0.0",
     "grammy": "^1.44",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
     "posthog-node": "^5.29.2"
   },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4"
+  },
   "engines": {
     "node": ">=20.11.0"
   },

package/telegram-plugin/quota-watch.ts

@@ -97,9 +97,10 @@ export function emptyAccountState(): QuotaWatchAccountState {
  *   SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP       "0" disables the broker claim
  *                                            (every agent sends, pre-incident
  *                                            behaviour)
- *   SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL "1" restores sending from
- *                                            cached data when the pre-send
- *                                            validation probe fails
+ *
+ * When the pre-send validation probe fails, the alert is unconditionally
+ * suppressed (a quota notification must never carry numbers we could not
+ * verify live); the transition re-evaluates on the next poll tick.
  */
 export interface QuotaWatchTuning {
   /** Cached snapshots older than this are treated as unknown (no opinion). 0 = off. */
@@ -108,8 +109,6 @@ export interface QuotaWatchTuning {
   lateRecoveryMs: number;
   /** Route sends through the broker's claim-notification dedup. */
   fleetDedup: boolean;
-  /** Legacy: send from cached data when the validation probe fails. */
-  sendOnProbeFail: boolean;
 }
 
 export const DEFAULT_QUOTA_WATCH_MAX_STALE_MS = 60 * 60_000;
@@ -133,7 +132,6 @@ export function resolveQuotaWatchTuning(
     maxStaleMs: num(env.SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS, DEFAULT_QUOTA_WATCH_MAX_STALE_MS),
     lateRecoveryMs: num(env.SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS, DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS),
     fleetDedup: env.SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP !== "0",
-    sendOnProbeFail: env.SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL === "1",
   };
 }
 

package/telegram-plugin/registry/turns-schema.test.ts

@@ -21,6 +21,7 @@ import {
   recordTurnEnd,
   findRecentTurnsForChat,
   getTurnByKey,
+  reapStaleOpenTurns,
 } from './turns-schema.js'
 
 // ---------------------------------------------------------------------------
@@ -157,3 +158,99 @@ describe('getTurnByKey', () => {
     db.close()
   })
 })
+
+// ---------------------------------------------------------------------------
+// reapStaleOpenTurns — mid-session periodic orphan sweep (#2918)
+// ---------------------------------------------------------------------------
+
+describe('reapStaleOpenTurns (#2918 mid-session sweep)', () => {
+  // Helper: force a row's started_at into the past so the TTL gate is met.
+  function ageRow(db: ReturnType<typeof openTurnsDbInMemory>, turnKey: string, startedAt: number): void {
+    db.prepare('UPDATE turns SET started_at = ? WHERE turn_key = ?').run(startedAt, turnKey)
+  }
+
+  it('stamps an ownerless open row aged past the TTL as restart', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:dead', chatId: '111' })
+    ageRow(db, 'dm:dead', now - 30 * 60_000) // 30 min old
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(), // process gone → no live owner
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(1)
+    expect(res.reapedTurnKeys).toEqual(['dm:dead'])
+    const turn = getTurnByKey(db, 'dm:dead')
+    expect(turn?.ended_at).toBe(now)
+    expect(turn?.ended_via).toBe('restart')
+    db.close()
+  })
+
+  it('NEVER touches a healthy in-flight turn (turn_key in activeTurnKeys)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:live', chatId: '222' })
+    // Even though it is aged well past the TTL, a live owner protects it.
+    ageRow(db, 'dm:live', now - 6 * 60 * 60_000) // 6h "long-running" turn
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set(['dm:live']),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    const turn = getTurnByKey(db, 'dm:live')
+    expect(turn?.ended_at).toBeNull()
+    expect(turn?.ended_via).toBeNull()
+    db.close()
+  })
+
+  it('does not reap an ownerless row younger than the TTL (race guard)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:fresh', chatId: '333' })
+    ageRow(db, 'dm:fresh', now - 60_000) // 1 min old, ownerless
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    expect(getTurnByKey(db, 'dm:fresh')?.ended_at).toBeNull()
+    db.close()
+  })
+
+  it('reaps the dead orphan while sparing a concurrently-live turn', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:dead', chatId: '111' })
+    recordTurnStart(db, { turnKey: 'dm:live', chatId: '222' })
+    ageRow(db, 'dm:dead', now - 30 * 60_000)
+    ageRow(db, 'dm:live', now - 30 * 60_000)
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set(['dm:live']),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reapedTurnKeys).toEqual(['dm:dead'])
+    expect(getTurnByKey(db, 'dm:dead')?.ended_via).toBe('restart')
+    expect(getTurnByKey(db, 'dm:live')?.ended_at).toBeNull()
+    db.close()
+  })
+
+  it('leaves already-ended rows alone (idempotent)', () => {
+    const db = openTurnsDbInMemory()
+    const now = 1_000_000_000_000
+    recordTurnStart(db, { turnKey: 'dm:done', chatId: '444' })
+    ageRow(db, 'dm:done', now - 30 * 60_000)
+    recordTurnEnd(db, { turnKey: 'dm:done', endedVia: 'stop' })
+    const res = reapStaleOpenTurns(db, {
+      activeTurnKeys: new Set<string>(),
+      ttlMs: 15 * 60_000,
+      now,
+    })
+    expect(res.reaped).toBe(0)
+    expect(getTurnByKey(db, 'dm:done')?.ended_via).toBe('stop')
+    db.close()
+  })
+})

package/telegram-plugin/registry/turns-schema.ts

@@ -497,6 +497,84 @@ export function markOrphanedWithTimeoutClassification(
   return { reaped: (timeoutTurnKey ? 1 : 0) + rest.changes, timeoutTurnKey }
 }
 
+export interface ReapStaleOpenTurnsOpts {
+  /**
+   * The set of turn_keys that belong to a turn still LIVE in this process's
+   * memory (the gateway's `currentTurnMap` registry keys plus the singleton
+   * `currentTurn` mirror). A row whose turn_key is in this set is NEVER
+   * reaped — it is a genuinely in-flight turn whose spinner must keep
+   * spinning, however long it runs. This is the load-bearing liveness
+   * predicate: age alone must never reap; only an open row with NO live
+   * owner qualifies.
+   */
+  activeTurnKeys: ReadonlySet<string>
+  /**
+   * Minimum age (ms, measured from `started_at`) before an ownerless open row
+   * is swept. A secondary guard against races — a turn that has JUST started
+   * but not yet populated the live set (or a row recorded microseconds ago) is
+   * protected until it ages past this. Liveness (activeTurnKeys) does the real
+   * work; the TTL only closes the "recorded-but-not-yet-tracked" window.
+   */
+  ttlMs: number
+  /** Injectable clock for tests. */
+  now?: number
+}
+
+export interface ReapStaleOpenTurnsResult {
+  /** Rows stamped `ended_via='restart'` by this sweep. */
+  reaped: number
+  /** The turn_keys that were stamped, for logging / card finalization. */
+  reapedTurnKeys: string[]
+}
+
+/**
+ * Mid-session periodic reaper (#2918). The boot-time
+ * `markOrphanedWithTimeoutClassification` only runs once, right after
+ * `openTurnsDb` — so a turn whose owning process dies MID-session (the SDK
+ * subprocess is SIGKILLed / OOMs / crashes) without a clean `recordTurnEnd`
+ * leaves its row `ended_at IS NULL`, and its activity card keeps spinning
+ * until the NEXT gateway boot (often many hours later). This sweep runs on a
+ * periodic timer inside the live gateway and stamps those ownerless open rows
+ * `ended_via='restart'` (the same clean-interrupt classification the boot
+ * reaper uses for a non-hung orphan) so the stale card can be finalized
+ * without waiting for a restart.
+ *
+ * CORRECTNESS: only rows that are BOTH (a) not owned by any live turn
+ * (`turn_key ∉ activeTurnKeys`) AND (b) older than `ttlMs` are swept. A
+ * healthy in-flight turn — however long it runs — is always in
+ * `activeTurnKeys` and is never touched. Never invents a new state; reuses
+ * `'restart'` so the existing resume/report policy applies unchanged.
+ */
+export function reapStaleOpenTurns(
+  db: SqliteDatabase,
+  opts: ReapStaleOpenTurnsOpts,
+): ReapStaleOpenTurnsResult {
+  const now = opts.now ?? Date.now()
+  const cutoff = now - opts.ttlMs
+  // Candidate = open row aged past the TTL. Liveness is filtered in JS against
+  // the injected active set (avoids brittle SQL IN-list binding).
+  const candidates = db.prepare(`
+    SELECT turn_key FROM turns
+    WHERE ended_at IS NULL AND started_at <= ?
+  `).all(cutoff) as { turn_key: string }[]
+
+  const stamp = db.prepare(`
+    UPDATE turns
+    SET ended_at   = ?,
+        ended_via  = 'restart',
+        updated_at = ?
+    WHERE turn_key = ? AND ended_at IS NULL
+  `)
+
+  const reapedTurnKeys: string[] = []
+  for (const { turn_key } of candidates) {
+    if (opts.activeTurnKeys.has(turn_key)) continue // live — never reap
+    const r = stamp.run(now, now, turn_key) as { changes: number }
+    if (r.changes > 0) reapedTurnKeys.push(turn_key)
+  }
+  return { reaped: reapedTurnKeys.length, reapedTurnKeys }
+}
+
 /**
  * Return the most recent N turns for `chatId` (any state — running or ended),
  * ordered by started_at DESC. Used by the idle-footer renderer to decide

package/telegram-plugin/render/ir.ts

@@ -0,0 +1,209 @@
+// Typed intermediate representation (IR) for the Telegram HTML render engine.
+//
+// This is the parser <-> renderer contract. `parse()` (parse.ts) folds an
+// mdast tree into this shape; a later increment's renderer walks it and emits
+// Telegram Bot API HTML. Increment 1 lands ONLY the parser + this IR — there
+// is no renderer yet.
+//
+// Every node carries `{ start, end }` UTF-16 source offsets copied verbatim
+// from mdast `position.start.offset` / `position.end.offset`. They are UTF-16
+// code-unit indices into the original markdown string, so
+// `source.slice(node.start, node.end)` round-trips to the node's source text.
+//
+// Telegram HTML tag mapping (for the next increment — NOT implemented here):
+//
+//   Inline
+//     plain     -> (raw text, HTML-escaped)
+//     bold      -> <b>…</b>                 (markdown `**…**`)
+//     italic    -> <i>…</i>                 (markdown `*…*`)
+//     underline -> <u>…</u>                 (markdown `__…__`, Bot API 10.1)
+//     strike    -> <s>…</s>                 (markdown `~~…~~`)
+//     spoiler   -> <tg-spoiler>…</tg-spoiler> (markdown `||…||`)
+//     highlight -> <mark>…</mark>           (markdown `==…==`, Bot API 10.1)
+//     code      -> <code>…</code>
+//     link      -> <a href="…">…</a>
+//
+//   Block
+//     paragraph      -> children joined; blocks separated by "\n\n"
+//     heading        -> <b>…</b> (Telegram HTML has no <h1>…<h6>; bold + newlines)
+//     blockquote     -> <blockquote>…</blockquote>
+//                       (expandable === true -> <blockquote expandable>)
+//     code-block     -> <pre><code class="language-…">…</code></pre>
+//     list           -> rendered line-per-item with "•"/"1." bullets
+//                       (Telegram HTML has no <ul>/<ol>)
+//     thematic-break -> a horizontal-rule text line (e.g. "───")
+//     table          -> monospaced <pre> table (Telegram HTML has no <table>)
+
+export interface Pos {
+  /** UTF-16 code-unit offset of the node's first char (mdast position.start.offset). */
+  start: number;
+  /** UTF-16 code-unit offset just past the node's last char (mdast position.end.offset). */
+  end: number;
+}
+
+// ---------------------------------------------------------------------------
+// Inline nodes
+// ---------------------------------------------------------------------------
+
+export interface PlainNode extends Pos {
+  type: "plain";
+  text: string;
+}
+
+export interface BoldNode extends Pos {
+  type: "bold";
+  children: Inline[];
+}
+
+export interface ItalicNode extends Pos {
+  type: "italic";
+  children: Inline[];
+}
+
+/** Telegram underline (<u>…</u>). In Bot API 10.1 rich markdown the `__…__`
+ *  double-underscore run is UNDERLINE — distinct from `**…**` bold, even though
+ *  GFM/micromark folds both into a single `strong` mdast node. `parse.ts`
+ *  disambiguates the two by looking at the run's source delimiter. */
+export interface UnderlineNode extends Pos {
+  type: "underline";
+  children: Inline[];
+}
+
+export interface StrikeNode extends Pos {
+  type: "strike";
+  children: Inline[];
+}
+
+/** Telegram spoiler (<tg-spoiler>…</tg-spoiler>), markdown `||…||`. GFM has no
+ *  spoiler syntax, so `parse.ts` recognises the `||…||` delimiter in a
+ *  post-parse pass over `plain` text. */
+export interface SpoilerNode extends Pos {
+  type: "spoiler";
+  children: Inline[];
+}
+
+/** Telegram highlight / marked text (<mark>…</mark>), markdown `==…==` (Bot API
+ *  10.1). Like spoiler, recognised by `parse.ts` in a post-parse pass over
+ *  `plain` text (GFM has no highlight syntax). */
+export interface HighlightNode extends Pos {
+  type: "highlight";
+  children: Inline[];
+}
+
+export interface CodeNode extends Pos {
+  type: "code";
+  text: string;
+}
+
+export interface LinkNode extends Pos {
+  type: "link";
+  href: string;
+  children: Inline[];
+}
+
+export type Inline =
+  | PlainNode
+  | BoldNode
+  | ItalicNode
+  | UnderlineNode
+  | StrikeNode
+  | SpoilerNode
+  | HighlightNode
+  | CodeNode
+  | LinkNode;
+
+// ---------------------------------------------------------------------------
+// Block nodes
+// ---------------------------------------------------------------------------
+
+export interface ParagraphNode extends Pos {
+  type: "paragraph";
+  children: Inline[];
+}
+
+export interface HeadingNode extends Pos {
+  type: "heading";
+  /** 1..6 */
+  level: number;
+  children: Inline[];
+}
+
+export interface BlockquoteNode extends Pos {
+  type: "blockquote";
+  children: Block[];
+  /** Telegram <blockquote expandable>. Always false in Increment 1 — see parse.ts. */
+  expandable: boolean;
+}
+
+export interface CodeBlockNode extends Pos {
+  type: "code-block";
+  text: string;
+  language: string | null;
+}
+
+export interface ListNode extends Pos {
+  type: "list";
+  ordered: boolean;
+  // NOTE: the spec names this ordinal `start`, but every node already carries
+  // `start`/`end` UTF-16 offsets (load-bearing for round-trip slicing). To
+  // avoid the collision the ordered-list ordinal is `startNumber` here; its
+  // semantics match the spec's `list.start` exactly (mdast `list.start`).
+  /** First number of an ordered list (mdast `start`); null for unordered. */
+  startNumber: number | null;
+  /** Loose vs tight (mdast `list.spread`). A LOOSE list separates its items
+   *  with a blank line in the source; a TIGHT list keeps them on adjacent
+   *  lines. The renderer preserves this: loose lists join items with a blank
+   *  line, tight lists (including nested sub-lists) stay on single newlines so
+   *  no spurious blank line is injected between a tight item and its sub-list. */
+  spread: boolean;
+  items: ListItem[];
+}
+
+export interface ThematicBreakNode extends Pos {
+  type: "thematic-break";
+}
+
+export interface TableNode extends Pos {
+  type: "table";
+  header: TableRow;
+  rows: TableRow[];
+  /** Per-column alignment, parallel to the cells. */
+  align: ("left" | "center" | "right" | null)[];
+}
+
+export type Block =
+  | ParagraphNode
+  | HeadingNode
+  | BlockquoteNode
+  | CodeBlockNode
+  | ListNode
+  | ThematicBreakNode
+  | TableNode;
+
+// ---------------------------------------------------------------------------
+// Composite / container shapes
+// ---------------------------------------------------------------------------
+
+export interface ListItem extends Pos {
+  children: Block[];
+  /** GFM task-list state: true (checked), false (unchecked), null (not a task item). */
+  checked: boolean | null;
+  /** Loose vs tight at the ITEM level (mdast `listItem.spread`): whether this
+   *  item's own block children are separated by a blank line in the source.
+   *  A tight item (spread=false) — e.g. a paragraph followed by a nested
+   *  sub-list — keeps its children on single newlines, so no blank line is
+   *  injected before the sub-list. */
+  spread: boolean;
+}
+
+export interface TableRow extends Pos {
+  cells: TableCell[];
+}
+
+export interface TableCell extends Pos {
+  children: Inline[];
+}
+
+export interface Document {
+  blocks: Block[];
+}