docs(markdown): apply the plugin architecture review to AST-036

[cixzhang]

User need

Markdown builders need one understandable extension model that supports parser syntax and document-wide semantic transformation without making each use case a separate protocol phase.

Decision

The protocol exposes only:

• syntax for source constructs the parser cannot already represent;
• immutable transform for document-wide semantic changes;
• typed renderers for extension nodes.

Text matching, semantic fences, and source decoration are helper-authored transforms. The canonical document is a strictly typed, MDAST-aligned tree shared by parsing, transformation, Markdown rendering, and Outline projection.

Zero-breaking gate

Existing parser signatures/results, components, inlinePlugins, math, citations, autolinks, DOM/accessibility, heading and Outline identity, navigation/resource policy, streaming reuse, and no-plugin behavior remain unchanged. Inline transforms remain phrasing-only. components.code always wins over semantic-fence helper output.

Limited Remark profile

A separate tree-shakeable adapter may run synchronous transform-only Remark plugins over the explicit node/field matrix in AST-036. Async work, parser/compiler hooks, processor state, raw HTML, forged positions, and unsupported nodes fail closed to the last valid readable document. Compatibility is proven per plugin, never inferred from package identity.

Evidence contract

AST-036 now includes:

• canonical MDAST node/field and permitted-edit matrices;
• source-backed versus synthetic fallback rules;
• exact parser and transform performance budgets;
• an explicit paired benchmark protocol;
• a contract-to-evidence verification table.

Scope

This PR changes authoritative knowledge records only. Runtime work is split into separately reviewable implementation PRs after this specification lands.

Validation

• node scripts/check-knowledge.mjs
• Prettier
• git diff --check
• Two independent spec reviews: no remaining P0/P1 writing or zero-breaking compatibility findings

---

Update — architecture review applied (2026-09-16)

An architecture review of this protocol and its implementation stack was adopted in full as approved direction. AST-036 keeps FR1–FR24 unchanged in number and meaning so existing citations resolve; everything new is FR25–FR41 and DEC-5…DEC-11.

• Extension containers. An extension node declares its content — 'none', 'phrasing', 'flow', or a narrowing {allow, min?, max?} allowlist. Core parses a container's inner source span and validates children, so a callout holds real Markdown instead of a literal string. Plugins never build children from raw source. The released top-level heading-identity traversal is deliberately unchanged: a heading inside a container behaves like one inside a blockquote.
• Ownership. Foreign nodes and source headings may be read and removed — including a subtree containing them — but never minted, edited, duplicated, or re-levelled. Rejections name the rule and the owner. dependsOn turns a reading plugin's ordering assumption into a validated, diagnosable one.
• Diagnostics. One source-free, rate-limited onPluginDiagnostic channel covers admission, syntax, transform, render, and adapter phases in development and production. Admission and version skew degrade instead of throwing, refused thenables are neutralized, and entry identity survives a duplicated Core copy.
• Authoring and packaging. Extension types are inferred from the declaration, the canonical AST gets public parse entrypoints, a server-safe parser entry exists beside the adapter entry, and a conformance kit exports the fixtures third parties need for per-plugin evidence.
• Performance. Budgets now name the path they measure, with separate plugin-authored and streaming ceilings and a bounded per-transform guard cost, so no one benchmarks against the first-party helper path.
• Also settled. Streaming transform idempotence, an opt-in extension theme target, prepared-list reuse for equal lists, a published protocol-stability policy, a reserved Core node-data namespace, a first-party plugin set built only on the public protocol, an inlinePlugins codemod migration after parity, a consumer-facing compatibility summary, and footnotes/definitions kept as Core scope rather than a plugin surface.

Owner records updated alongside: component:Markdown FR17–FR22 and DEC-3, and module:Outline/parseOutlineFromMarkdown FR4, FR7–FR9, and DEC-2.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 16, 2026 6:15pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟡 Reviewed (for maintainers only)	Sep 16, 2026, 6:16 PM UTC

[cixzhang]

/approve-spec 8ac3bc1