From 8da40a2802a4f328363ec653fe7fbf1b86e6cbfd Mon Sep 17 00:00:00 2001
From: Oscar Villavicencio <odvcencio@gmail.com>
Date: Sat, 1 Aug 2026 01:36:25 -0700
Subject: [PATCH] document(external-scanners): Document Markdown scanner
 certification

- Document the certified checkpointed reuse contract for block-level Markdown and the fallback behavior for markdown_inline.
- Verify production exposes both scanner contracts to prevent documentation drift.
---
 content/docs/external-scanners.md | 26 ++++++++++++++++++++++++++
 scripts/verify-production.sh      |  5 +++++
 2 files changed, 31 insertions(+)

diff --git a/content/docs/external-scanners.md b/content/docs/external-scanners.md
index c0a0d8e..b812444 100644
--- a/content/docs/external-scanners.md
+++ b/content/docs/external-scanners.md
@@ -297,6 +297,32 @@ remapper: `gotreesitter.AdaptExternalScannerByExternalOrder(sourceLang, targetLa
   returning false never mutated the payload — this lets the runtime skip defensive state
   snapshots on the hot path.
 
+### Markdown scanner certification matrix
+
+[PR #455](https://github.com/odvcencio/gotreesitter/pull/455) certifies only
+the block-level `markdown` scanner. Its
+[merge commit `91a5dccc`](https://github.com/odvcencio/gotreesitter/commit/91a5dccc01904dd18d75d7ea84b3a01a67b356c2)
+records the proof.
+
+The `markdown` scanner-dependent route records scanner checkpoints. A changed
+edit can enter old-tree reuse only for a clean old tree. The normal dirty-span,
+fragility, byte-equality, parser-state, and scanner-boundary gates still apply.
+
+The proof compares each incremental tree with a fresh production parse. It
+covers insert, delete, and changed-length replace edits at the start, middle,
+and end of 8 KiB clean documents. It also requires 25% reused bytes for a
+middle replace in a 256 KiB document. It does not promise O(edit) time.
+
+The `markdown_inline` scanner remains uncertified. After the token-invariant
+leaf fast path declines, its changed edits use the production full-parse
+fallback. The Markdown proof does not apply to `markdown_inline` or
+error-bearing old Markdown trees.
+
+| Language | Changed-edit contract |
+|---|---|
+| `markdown` | Certified checkpointed reuse for clean old trees. |
+| `markdown_inline` | Fallback (uncertified) after the leaf fast path declines. |
+
 ## Hard-learned behavioral contracts
 
 These four contracts came out of this project's C-parity work. They apply mainly when you
diff --git a/scripts/verify-production.sh b/scripts/verify-production.sh
index 6b476d3..4186dd7 100755
--- a/scripts/verify-production.sh
+++ b/scripts/verify-production.sh
@@ -127,6 +127,11 @@ done < <(
 
 curl --silent --fail "$base/" | grep -q 'Certified fresh parsing' || fail "landing route contract missing from /"
 curl --silent --fail "$base/docs/performance" | grep -q '5.526× C' || fail "performance geomean (5.526× C) missing from /docs/performance"
+external_scanners_html="$(curl --silent --show-error --fail "$base/docs/external-scanners")"
+grep -Fq 'Certified checkpointed reuse for clean old trees.' <<<"$external_scanners_html" ||
+  fail "Markdown clean-tree reuse contract missing from /docs/external-scanners"
+grep -Fq 'Fallback (uncertified) after the leaf fast path declines.' <<<"$external_scanners_html" ||
+  fail "Markdown Inline fallback contract missing from /docs/external-scanners"
 curl --silent --show-error --fail --output "$page_body" "$base/changelog"
 grep -q 'History you can interrogate' "$page_body" || fail "changelog hero missing from /changelog"
 grep -q 'v0.48.0' "$page_body" || fail "v0.48.0 missing from /changelog"