myform — the universal graph, and documents that communicate

Spec of record for the post-1.0 horizon, as of 2026-08-05: drafted, reviewed by the operator, and revised against decisions D1–D6 and follow-ups O1–O3 (§7). No question is open. Drafted against myform 1.0.0. Successor horizon to myform-spec.md, which this document assumes and does not restate. Origin: operator ask — cannibalize corpus mdsite/myst-report into myform; assess the universal-translator claim; extend the graph to HTML, wikitext, and Obsidian. O3 extended that set to LaTeX, docx, and the incidental Markdown flavors (§P10–P12, §3.11).

1. Where we actually stand

1.1. The good news is structural

myform 1.0.0 is not “a translator that happens to support four formats.” It is a hub, and the hub is the whole point:

• Adding a format costs 2 units of work, not N. One reader, one writer. The 4×4 matrix is 16 cells built from 8 modules.

• Each new format adds 2N-1 cells for free. Going from 4 formats to 7 takes the graph from 16 cells to 49 — for six new modules, not thirty-three new converters.

• The audit grows itself. tests/test_matrix_sweep.py reads Reader.REGISTRY and the writer registry at collection time. A new format registers and the sweep expands without anyone editing the test.

That is the bold claim already paid for. Everything below is an argument about what to spend the next increment on, not about whether the architecture holds.

Two corrections this document later makes to its own arithmetic, flagged here so the optimistic version above is not read alone. Seven is not the horizon — §3.11 puts nine engines plausibly in scope and §P10 adds dialects on top, so the real figure is nearer 169 cells than 49. And the self-growing audit is a liability at that size as surely as it is an asset at this one: a sweep that expands without being edited also expands without being budgeted. §4 makes both explicit and prices them.

1.2. Three gaps stand between here and “universal translator”

Gap A — the hub has no web terminal. Every format myform speaks is an authoring format. HTML is the universal sink: it is where documents go in order to be read by someone. A translator that cannot emit HTML can translate documents but cannot finish the job of communicating them.

One nuance, added after D4: the renderer was never the problem. mdsite builds on Sphinx, and should — that is the institutional center, not a workaround. What is a workaround is the 300-odd lines of regex that patch mdsite’s inputs into shape before Sphinx sees them, because nothing upstream could parse the documents it was collecting. The gap is a parser gap, not a renderer gap.

Gap B — there is no collection layer. The entire public surface is convert(text, src, dst): one document, no identity, no neighbors. Real communication artifacts are N documents with links between them. mdsite’s manifest.json plus doc_url() is an embryonic cross-document resolver, hand-rolled in a script, outside the type system.

Gap C — “95% native” is currently undefinable, let alone unmeasured. The parts exist — Capability per (writer, node kind), MappingGrade per reader construct, a registry-driven sweep — but there is no denominator, no weighting rule, no corpus of record, and no floor. The claim cannot be made honestly today. It also cannot be disproved, which is worse.

1.3. One thing that is nearly there

Nothing a reader saw is ever unrecoverable in the tree: Unknown, Ignored, and SyntaxRaw (with its MappingGrade) guarantee that. But at the writer boundary the fates collapse to APPROX, CARRY, DROP — all three of which are in-band: the content is approximated in place, reduced in place, or deleted.

The operator’s phrase was “the rest being safely demarcated and linked.” That is a fourth fate — preserved out-of-band, referenced in-band — and it does not exist yet. It is the single most valuable missing primitive in the system (§P2).

2. The ask, restated

Three things, treated as one investigation:

1. Absorb corpus mdsite and myst_report as first-class myform functionality.

2. Assess and extend the translator graph toward HTML.

3. Add wikitext (MediaWiki) and Obsidian-flavored Markdown.

Assumption, since confirmed. The parenthetical “(& mas?)” in the original ask was read as “y más” — “and more?” — and the operator confirmed it. The follow-ups filled it in: wikitext and Obsidian first, then O3’s LaTeX, docx, and “incidental flavors of markdown.” §P10–P12 propose those, and §3.11 discharges O3’s second half by recording, per format, exactly what makes it cheap or expensive.

2.1. Two terminals, not one pipeline (O1, answered)

O1 answered: to-PDF and to-HTML are separate goals that only sometimes coincidentally share infrastructure.

That is a sharper ruling than the “both, per document” resolution §P5 originally proposed, and it settles a question that would otherwise be re-litigated at every format:

Terminal	Purpose	Document scale	Collection scale
to-HTML	be read on the web — searchable, linkable, indexed	an HTML fragment (P1)	a Sphinx site (P5)
to-PDF	be typeset for print — pagination, typography	typst compile; LaTeX (P11)	Sphinx’s own LaTeX builder

What “separate goals” forbids. Neither terminal is a fallback for the other. A PDF is not compensation for what HTML could not render, and an HTML page is not a preview of a PDF. Concretely, a compiled artifact a site links is a link, not an ENCLAVE (§P2): an enclave exists because a target cannot express a construct, whereas a Typst document translated to a MyST page was expressed — the PDF beside it is a peer deliverable the same collection happened to produce. Routing it through the enclave mechanism would re-couple precisely what this ruling decouples.

What “sometimes coincidentally share infra” permits. Both terminals consume the same Doc and the same Collection (P4), and one myform site run may legitimately produce both. Sharing the front half of the pipeline is fine; deriving one goal’s quality bar from the other’s is not.

Consequence for §5.4. corpus.typst’s shelling of the typst binary is to-PDF infrastructure — feature-detected and optional, and its absence degrades the PDF goal only, never the site. This is also why P1 and P11 are not redundant with Sphinx’s own builders: myform’s writers are document-scale termini, Sphinx’s builders are collection-scale ones, and neither displaces the other.

3. Proposals

Ordered by dependency, not by size. P2 and P4 carry the architecture; everything else is cheaper once they land. P1 was originally the third load-bearing member, but D4 removed the dependency that made it so, and O2 moved it to wave 2 accordingly — see §P1 and §7.

P1–P9 answer the original ask; P10–P12 answer O3, and §3.11 records what O3 asked to have recorded.

3.1. P1 — The HTML writer

Proposal. Doc → semantic HTML5, as an ordinary writer in the existing seam.

Scope: a document fragment by default, an optional standalone wrapper; Target nodes become stable id attributes; Code becomes <pre><code class="language-...">; Math emits MathML or delimiter-preserved spans for a client-side renderer (decision D3); no CSS framework, no JavaScript, no theme opinions — those belong to P5.

What the D4 reversal cost it, stated plainly. Two of P1’s four original justifications were downstream of the native-site plan and died with it. It no longer “closes the sink” — Sphinx emits the site’s HTML. And the sidecar-free <details> enclave is now a P1-only convenience rather than the primary path (§P2).

What survives, and still justifies building it.

• HTML is the capability ceiling, and that makes it a measurement instrument. HTML can render essentially every node kind in the tree natively. Once that is true and tested, coverage for every other target is measured against a known-achievable top rather than an imagined one. P3 is much weaker without it.

• convert(text, ..., 'html') is a real want independent of any site — a fragment for an email, a paste, an issue comment, a CMS. That is the ordinary translator use case, and it needs no site machinery at all.

• Cleanest possible seam fit: a Writer subclass and a capability table, lazy-loaded exactly like RstWriter/TypstWriter via _DIRECT_WRITERS. test_matrix_sweep.py picks it up with no edit — 4 audited cells immediately, 7 once §3.7–3.9 land.

Sequencing, settled (O2 — delegated to the author, §7). P1’s wave-1 rationale was “unblocks P5,” and D4 made that false; nothing in wave 1 depends on P1. P1 therefore trades its wave-1 slot with P7 and moves to wave 2, immediately ahead of P3. The reason is not that P1 matters less — it is that P1’s one surviving structural justification is being P3’s measurement ceiling, and P3 sits in wave 2. Splitting a dependency pair across waves would leave the dependency idle for an entire wave; moving P1 puts it adjacent to its only dependent, and leaves wave 1 as three mechanisms with no idle member (§7, D1 as amended).

Bonus. EPUB is HTML in a zip with a manifest. Once P1 exists, an EPUB writer is close to free — the only frontier-tier format worth an early card (§3.10).

3.2. P2 — ENCLAVE: the fifth capability

Proposal. Add a fifth Capability variant meaning: this content cannot be rendered natively, so it is preserved verbatim out-of-band and referenced in-band by a stable, typed marker.

Per-target realization:

Target	In-band marker	Out-of-band carrier
MyST → Sphinx site (primary)	admonition linking to the enclave page	the sidecar is a real staged page
MyST / GFM (standalone file)	admonition or blockquote + relative link	<doc>.enclaves/<hash>.<srcfmt>
rST	.. note:: + :download: or link	same sidecar
Typst	bordered #block + link	same sidecar
HTML (P1)	<details> disclosure, labelled by source fmt	none needed — inline

D4 promotes the first row from bonus to primary: inside a site, an enclave is a staged page plus an admonition pointing at it — navigable, searchable, and indexed by Sphinx like any other document. The <details> form is now a P1-only convenience.

Three required properties:

• Reversible. An enclave round-trips back to the original node when the reverse conversion runs. This is what makes it safe rather than merely polite.

• Addressable. Stable content-hash id — the same id every build, so links do not churn.

• Reportable. One ConversionReport entry, obeying the existing AC4 zero-silent-loss invariant unchanged.

Implemented carrier contract. convert_artifact() and Session.convert_artifact() return a ConversionArtifact: target text, its report, and validated typed EnclaveRecord carriers. Each record uses a full SHA-256 id and the canonical relative path enclaves/<id>.json; exact reader syntax is retained when source_raw exists. Each id binds the canonical typed payload, source format, and structural occurrence, while content_hash remains position-independent. An act is ENCLOSED only when the lowering returns that exact carrier, the report row binds its id and path, and the writer recovers a final typed target-native link. Marker-only legacy rules and raw path substrings are ordinary lossy replacements. Legacy text and text-plus-report APIs raise ArtifactRequiredError rather than discard a real carrier. No built-in writer adopts ENCLAVE until its target-specific marker/materialization contract has end-to-end tests.

Why it matters more than it looks. Today a construct that a target cannot express is lost information presented as a translation. An enclave is the opposite: honest, complete, and navigable. It converts the failure mode of the whole system from “quietly wrong” to “visibly deferred.” It is also the mechanism that makes wikitext tractable at all (§P8) — MediaWiki templates go into enclaves rather than into a promise we cannot keep.

Versioning consequence — flag for decision. Capability is part of the extension surface published at v1.0.0. Adding a variant is additive to the enum but changes the exhaustiveness contract for any third-party writer matching on it. Recommendation: v1.1, additive, with a documented fallback (a writer that does not know ENCLAVE degrades it to CARRY), rather than holding it for a v2. See D2.

3.3. P3 — A coverage instrument, and an honest definition of 95%

Proposal. Define the metric before building the tool, then publish both.

The definition. End-to-end nativeness is not a writer property. A construct read at MappingGrade.LOOSE and written at Capability.NATIVE was not natively translated — the loss happened on the way in. Therefore:

nativeness(node) = min(read grade, write capability), projected onto a common ordinal scale.

The denominator: characters, not nodes. Node-count coverage flatters the number badly — a document is mostly Text nodes, so counting nodes measures how much prose is prose. Weight by characters of rendered text content under each node. That is the fraction a human would recognize as “how much of my document came through.”

The corpus of record. Explicitly not tests/data/testcases.md — that file is adversarial by construction and coverage measured on it is meaninglessly low. Measure on real documents:

• ~/my/corpus/journal/reports/** — the fleet’s own prose, the actual use case.

• A pinned public sample per format: the CommonMark spec suite, a real Sphinx docs tree, a small Wikipedia article set, a sample Obsidian vault.

The surface. myform coverage [--from X] [--to Y] [--corpus PATH], emitting a per-cell table and a JSON sidecar; published as a CI artifact so the matrix table in the README can stop being hand-maintained prose and start being generated truth.

The floor. Per-cell and tiered (§4), not one global number. A single global “95%” would be gamed by the easy cells the moment it was adopted.

3.4. P4 — Collection: the missing abstraction above Doc

Proposal. A typed container for N documents with relationships:

class Collection(BaseModel):
    root: Path
    docs: dict[DocId, DocEntry]        # id -> source path, format, output rel, Doc
    order: NavTree                     # explicit or derived ordering/nesting

It owns two things no Doc can own alone — source→output mapping and intra-collection reference resolution — plus an ordering hint that P5 turns into a toctree.

D4 makes this smaller than first specced. Navigation rendering and full-text search are not Collection’s job: Sphinx’s toctree and its search index already own both. What remains is sharper for having been narrowed — resolve source-side references, and emit Sphinx-native cross-references from them.

Why this is an architecture proposal and not a site feature. Consider what a cross-document reference does today. An Obsidian [[Note]], a MyST {doc} role, a Sphinx :ref:, a wikitext [[Article]], a toctree entry — every one of them is a promise about a document that is not this one. With only a Doc, that promise is unresolvable, so every such construct is at best a CARRY.

Give the writer a Collection and the identical construct resolves to a real MyST {doc} / :ref: cross-reference, which Sphinx then wires up: CARRY becomes NATIVE for an entire class of nodes across every format simultaneously.

That means P4 is not a feature that sits beside P3 — P4 moves the P3 number, and it is the only proposal here that does so for many formats at once. It is also the precondition for Obsidian being worth anything (a vault is a collection or it is nothing) and for wikitext links resolving at all.

3.4.1. How a writer reaches a Collection — settled before coding

Writer.write(doc, options) has no collection parameter, and it must not grow one: that is a signature change across every writer and every third-party extension compiled against the v1.0.0 surface. The alternative that suggests itself — smuggling a live Collection through the options mapping — is worse, because MarkdownWriter.write forwards options straight into build_engine, i.e. into mdformat’s own options dict.

The seam already exists, and the architecture already names the pattern. Session._convert_with_report runs read → lower → write, where lower() exists precisely so that “writers never contain ‘if this can’t be rendered’ branches: the constraint lives in this one declared gate” (writers/base.py). Cross-document references get the identical treatment, one stage earlier:

doc = reader.read(text, options=source_options)
doc = resolve(doc, collection)                       # P4: cross-doc references become concrete
lowered, report = lower(doc, writer.capabilities, ...)
rendered = writer.write(lowered, options=target_options)

This is what makes the CARRY → NATIVE claim true rather than merely asserted. resolve() rewrites an unresolved cross-document reference into an ordinary Link or cross-reference node before lower() consults the capability table. The table therefore never sees the exotic kind at all — it sees a kind every writer already renders NATIVE. One pass upgrades every format simultaneously because no writer is edited, which is the same reason the degradation engine can add a lowering rule without touching a backend.

Two properties follow for free, and both matter:

• Additive in the strict sense. With no Collection supplied, resolve() is the identity: the reference keeps its unresolved kind and the capability tables treat it exactly as they do today. Single-document convert() is byte-for-byte unchanged.

• Reachable. The pass runs inside the real pipeline via Session.convert_in_collection, which returns three values rather than two. A pass that only tests can call is not a landed feature, however green its own suite.

• Reportable, but in its own report. An earlier draft of this section said a dangling reference should flow through ConversionReport. Building it showed that to be wrong: a degradation report records what a target could not express, whereas a dangling reference is neither approximated, replaced, dropped, nor enclosed — it is a promise the collection could not keep. Merging the two would make ConversionReport.lossy mean two different things at once. resolve() therefore returns its own ResolutionReport, and collection-wide link checking is a filter over those rather than a fourth pass.

3.5. P5 — myform site: cannibalizing mdsite (revised — D4 answered)

D4 was answered “Sphinx stays,” and the original proposal here was wrong. Sphinx, rST, and ExecutableBooks/MyST are the institutional center this project sits inside, alongside Typst; re-implementing a renderer that covers Sphinx’s interface is a bad trade at any size. And yes — mdsite does already build on Sphinx today. It stays there.

The corrected architecture. myform’s job is translation into Sphinx, never replacement of Sphinx:

Typst    ─┐
Obsidian ─┤                                       ┌─ conf.py + toctrees (generated)
wikitext ─┼→ myform readers → Doc → MyST writer ──┤
GFM      ─┤                                       └─ sphinx-build → furo HTML
rST/MyST ─┘  (already native; pass through)

The unlock the native path was reaching for survives intact, and is better served this way: Sphinx cannot read Typst, Obsidian, or wikitext — so myform converts them into MyST, and Sphinx does what it has always done. No renderer is rewritten. The input set grows from two formats to seven.

So myform site is: Collection (P4) + translate-every-source-to-MyST + generate conf.py and toctrees + shell sphinx-build + serve. Which is to say: mdsite’s existing architecture, with myform’s parser where the regex massage stage used to be.

The engineering win survives the pivot whole — and is now the main one. mdsite._massage exists because Sphinx needs its markdown pre-patched into compliance: regex-injecting missing # H1s, rewriting ad-hoc ## title: lines into YAML, masking fences so heading detection does not misfire. myform does not patch text; it parses it. A missing H1 is a Doc with no Heading at depth 1, fixed by a typed transform. That whole regex layer — and much of the suppress_warnings list beneath it — is deleted rather than reimplemented, because what reaches Sphinx is canonical MyST rather than agent-authored markdown of unknown quality.

Typst fidelity — O1, answered (§2.1). The question was whether routing typst → MyST → Sphinx regresses mdsite._render_typst’s compiled SVG+PDF output, which is the flagship path (corpus md → typst → PDF, me-myself.ai). The ruling is that to-PDF and to-HTML are separate goals, so the framing was wrong rather than the answer being close:

• myform site serves the to-HTML goal. A .typ source in a collection is translated to a MyST page: searchable, linkable, indexed by Sphinx like any other document. This is not a lossy approximation of the PDF — it is a different artifact with a different purpose.

• The to-PDF goal compiles that same .typ (or a Doc routed through the Typst writer) with the typst binary, when the operator asks for a PDF. It is a peer deliverable, not fidelity insurance.

• When both goals run over one collection, the site may link the compiled artifact. That link is an ordinary link — explicitly not an ENCLAVE, since nothing about the document was inexpressible (§2.1).

The practical consequence for P5 is a simplification: there is no per-document “translated or typeset?” toggle to design, because the two are not alternatives. myform site builds a site; myform pdf (or the existing corpus wrapper) builds PDFs; a collection may be handed to both. Typst compilation is feature-detected — no typst binary degrades the PDF goal only, never the site.

Packaging. myform[site] extra pulling sphinx + myst-parser + furo, every import function-local. import myform never touches them, so §5.1’s budget holds by construction rather than by vigilance.

There is no Stage B. The “native backend later” idea is withdrawn, not deferred.

3.6. P6 — myform site new: absorbing myst-report

corpus/myst_report.py is 188 lines that scaffold a Sphinx directory and shell sphinx-build. Under P5 both halves are already present. Recommendation: do not port it as a separate verb — it becomes myform site new <topic>: a template plus a Collection. Corpus keeps a thin myst-report wrapper (§5.4) so the command and its muscle memory survive.

3.7. P7 — Obsidian-flavored Markdown (wave 1, per O2)

Proposal. A dialect over the existing markdown engine (§P10) — not a new engine, but not free either: Extension band, because four of its constructs have no plugin behind them.

Obsidian construct	Maps to
[[Note]], [[Note|alias]]	Link, resolved through Collection — NATIVE with P4, CARRY without
![[Note]], ![[Note#^blk]]	transclusion — new Embed node, or Directive{include}
> [!tip]- Title	Directive admonition; fold state +/- → a dropdown option
%%comment%%	Comment — MyST % is the exact sibling
==highlight==	new phrasing node (or a Role)
#tag, ^blockid	frontmatter tags / Target
properties frontmatter	FrontMatter (already modeled)

(Syntax verified against current Obsidian docs, 2026-08-05.)

What building it settled. The dialect’s declaration is ('gfm', 'footnote', 'front_matters', 'obsidian') — Obsidian is GFM, plus footnotes, plus YAML properties, plus one plugin. Everything the table above does not mention (tables, task lists, strikethrough, autolinks, front matter) arrives from the stack beneath, and only the five constructs Obsidian actually invents needed new code. That is P10’s cost-band claim surviving contact with a real format, and it is why this is the proof of the dialect layer rather than merely its first customer.

Two model decisions worth carrying to later dialects:

• A wikilink is a Link with a spelling flag, not a node kind. Link.wiki is additive and defaults false, so every writer without wikilink syntax stays literally unmodified while obsidian → obsidian round-trips exactly. Minting a WikiLink node would have forced an entry into all five capability tables to say the same thing. Resolution defines collision behavior explicitly: an unqualified [[Note]] falls back to unique-basename lookup after exact path/id lookup fails, exactly one match resolves NATIVE, and multiple matches leave the spelling untouched with an AMBIGUOUS resolution entry naming every candidate in stable document-identity order – reported, never guessed.

• ==highlight== and ![[embed]] are genuinely new kinds, because nothing in the tree meant either. They cost one node class and one bridge registration each — the honest price of a construct the model did not have, and the counterexample that keeps the first decision from being a rule.

Deferred, and recorded rather than silently missing: inline %%comments%% mid-paragraph, #tag inline tags, and ^blockid identifiers. Dollar math is implemented rather than deferred: the Obsidian reader installs the dollarmath tokenizer before highlight parsing, and dedicated typed renderers emit inline and display math as $...$ and $$...$$. Those math nodes remain report-bearing APPROX because MyST equation-label semantics are not promised identical in Obsidian.

Why first — on value, not on cheapness. An earlier draft argued Obsidian was the cheapest new format. Checking the shelf disproved that: callouts have mdit_py_plugins.admon behind them, but wikilinks, ==highlight==, %%comment%%, and ![[embed]] have no plugin at all, so P7 needs a real markdown-it extension module. Pandoc-flavored is the cheaper first dialect (§3.11). P7 still goes first, for the reason that actually holds:

MyST and Obsidian are the closest pair in the entire matrix. Callouts are admonitions. %%...%% is %. Wikilinks are cross-references. Properties are frontmatter. myst ↔ obsidian should be near-lossless in both directions, which makes it an excellent Tier-1 correctness cell and by far the strongest early demonstration of the thesis — and, because its headline construct is the wikilink, the first real exercise of P4’s resolve() pass. Cheapest and most valuable are different questions, and this spec answers the second one.

3.8. P8 — Wikitext (MediaWiki), bounded

The honest assessment. MediaWiki has no formal grammar; its specification is the behavior of the PHP parser. This is the hardest format in the set by a wide margin, and the proposal is scoped accordingly.

What mwparserfromhell gives us (verified 2026-08-05): a node tree of Template, Wikilink, ExternalLink, Heading, Tag (including style ''/''' and wikitables), Comment, HTMLEntity, Argument, Text — and lossless round-trip by construction, since str(wikicode) reconstructs the source exactly. That round-trip property is a very good fit for SyntaxRaw + MappingGrade, which already exists for the Typst CST.

What it does not give us, and this is the load-bearing finding: it is a wikicode parser, not a document-structure parser — its tree is flat and marker-oriented, never containment-oriented. Verified empirically against mwparserfromhell 0.7.2 (2026-08-05):

• A list marker * is a Tag node, and the item’s text is a sibling Text node, not a child of it. There is no List, no ListItem, and no nesting depth anywhere in the tree.

• An entire wikitable arrives as one opaque Tag holding its raw source — no rows, no cells, no header structure.

• Paragraph breaks and indentation are undifferentiated Text.

• Round-trip is lossless (str(parse(src)) == src), which is the property that makes SyntaxRaw + MappingGrade a good fit.

So the reader is necessarily three-layer: mwparserfromhell for the template/link/style surface, a line-oriented block pass to assemble flat markers into real List/ListItem/DefinitionList containment, and a dedicated sub-parser for the opaque table blobs. Any plan that assumes one library does the job is wrong, and would discover it late — after committing to a wave.

Templates: promise nothing. A template is a function call into a wiki-specific library; expanding it correctly requires that wiki. Spec position:

• Default: every Template becomes an enclave (P2) — preserved verbatim, marked, linked.

• Optional: a configurable known-template map for the common shapes ({{cite ...}} → citation, {{quote}} → blockquote, infobox → table).

• Never: general template expansion.

This is the cleanest justification for P2 existing at all, and the reason P2 must land before P8.

Write before read. Emitting wikitext is a plain writer and is far easier than parsing it. If an early win is wanted, * → wikitext is available well before wikitext → *.

3.9. P9 — The HTML reader, scoped

Proposal. Read semantic HTML: our own P1 output, and reasonably structured documents (article, section, h1–h6, p, ul/ol, table, pre, figure, blockquote).

Explicitly out of scope: the open web. Arbitrary page HTML is tag soup, and “read HTML” silently becomes “decide what is content and what is chrome” — a readability/extraction problem, not a translation problem, and a different tool. Saying so in the spec prevents an unbounded subproject from growing inside a bounded one.

Target property: read_html(write_html(doc)) ≈ doc — round-trip against our own output, tested as a bridge property in the style of the existing token-bridge tests.

3.10. P10 — The Markdown dialect layer (O3, first half)

A finding first, because it changes the proposal. The dialect layer is not something to build. It is something already built twice and never named:

Module	Lines	Content
myform/readers/myst.py	30	a name and an extensions tuple
myform/readers/gfm.py	29	a name and an extensions tuple
myform/writers/myst.py	36	the above plus a capability table
myform/writers/gfm.py	49	the above plus a capability table
myform/readers/typst.py	964	(an engine, for contrast)

MyST and GFM are not two engines. They are two dialects of one engine, declared over the shared build_engine, and the cost of a third is a tuple and a table. That is why O3’s “add those where we can do so easily” is a real offer rather than an aspiration — and it also tells us exactly where “easily” stops.

The gate, stated as one question: does the flavor’s syntax already have a markdown-it / mdformat plugin behind it? Verified 2026-08-05, the installed shelf is deflist, footnote, front_matters, gfm, myst, tables; mdit_py_plugins additionally ships attrs, container, colon_fence, admon, dollarmath, texmath, field_list, tasklists, and subscript — parsers with no mdformat renderer attached to them yet.

Three cost bands follow, and every entry in §3.11 is classified by them:

Band	Cost	Meaning
Declaration	a tuple and a table, ~50 lines	every construct already has a plugin
Extension	+ one markdown-it plugin module	some constructs need a parse rule and a renderer
Engine	a reader/writer module pair, ~700–950	not markdown at all; a different grammar

Proposal. Promote the pattern to an explicit, documented seam: a Dialect declaration carrying its extension tuple, its capability table, and the one knob the current shape lacks — writer-side spelling choice. When two dialects can both express a construct but spell it differently (an admonition as a MyST directive, a GFM alert, or a Pandoc fenced div), that choice belongs in the declaration, not in a branch inside a writer. Dialects register through the existing Reader.register / Writer.register decorators, so nothing downstream changes — with one consequence that does need handling, in §4.

3.11. P11 — LaTeX (O3)

Write: a peer of the Typst writer, and a to-PDF terminal in its own right. writers/typst.py is 942 lines and is exactly the shape to copy — a direct backend, lazy-loaded through _DIRECT_WRITERS, with its own capability table. Per §2.1 this is a document-scale to-PDF terminus; Sphinx’s LaTeX builder remains the collection-scale one, and the two do not compete any more than P1 competes with Sphinx’s HTML builder.

Read: bounded, for a reason this spec has now met twice before. \newcommand makes LaTeX macro expansion Turing-complete and package-dependent: reading arbitrary LaTeX correctly requires that document’s preamble and packages, exactly as reading wikitext correctly requires that wiki (§P8). The position is therefore identical — parse the document-structure surface (sectioning, environments, \emph, math, tables, \label/\ref), map a curated set of known commands, and make every unrecognized macro or environment an enclave (P2). Never expand. Candidate parser: pylatexenc, which walks macros without expanding them. To be verified before P11 is scheduled, not assumed here.

3.12. P12 — docx (O3)

Write: mechanical, and the frontier format with the largest audience outside this fleet. A .docx is a zip holding document.xml and a handful of sibling parts. Emitting the subset myform’s tree needs — headings, paragraphs, runs with bold/italic/code, lists via numbering.xml, tables, images, hyperlinks — is bounded XML generation with no parsing in it. python-docx behind a myform[docx] extra removes the package plumbing entirely; a hand-rolled minimal package avoids the dependency. Recommend the extra, consistent with §5.1.

Read: honestly lossy, and the reason is structural rather than incidental. Word’s model is presentational. A heading is a paragraph wearing a style named Heading 1, and nothing stops a document from styling its headings by hand instead — in which case the semantic heading is simply not present in the file. Recovery is therefore heuristic, which is precisely the thing MappingGrade exists to record: a styled document reads EXACT, a hand-formatted one reads RESONANT or worse, and the grade is reported rather than hidden.

This makes docx the first format whose read grade will routinely vary within a single document, which is a genuinely useful stress test of §P3’s min(read grade, write capability) definition — the one place where a naive per-format average would lie.

3.13. Frontier tier — what is left after O3

O3 promoted LaTeX (P11) and docx (P12) out of this tier. What remains: AsciiDoc, Org-mode, man, Textile, Djot, EPUB. The architecture must not preclude them; this increment must not wait for them.

Recommended cut, unchanged: EPUB write only, and only because it is nearly free once P1 exists (HTML in a zip with a manifest) — and note that EPUB is a to-HTML terminal, so it inherits P1 rather than P11. Of the rest, Djot is the most tractable engine-tier candidate by a wide margin, being the one with a clean formal grammar rather than a reference implementation standing in for a specification. Everything else is deferred with no work now.

3.14. The specialized-work ledger (O3, second half)

O3 asked to “record the outstanding cases that might require specialized work.” This is that record: every format considered, its band (§P10), and the specific thing that makes it cheap or expensive.

Format	Band	What decides it	Position
CommonMark (strict)	Declaration	the GFM stack minus its extensions	free; take it with P10
Pandoc-flavored	Extension	deflist/footnote/tables shipped; fenced divs and bracketed spans have mdit parsers (container, attrs) but no mdformat renderers; line blocks, grid tables, and [@cite] need rules	the cheapest proof of P10
Quarto (.qmd)	Extension	Pandoc-flavored + YAML header + executable cells (Code with attributes) + {{< shortcodes >}}	near-free once Pandoc lands
Obsidian	Extension	callouts have admon; wikilinks, ==highlight==, %%comment%%, ![[embed]] have nothing	P7, wave 1
kramdown / MultiMarkdown	Extension	{: .class} inline attribute lists are attrs-adjacent	opportunistic
Quarkdown	Extension (write)	a CommonMark/GFM superset, so valid GFM output is already valid Quarkdown — the writer is a spelling choice plus optional .doctype/layout emission	write is nearly free
Quarkdown	bounded (read)	Kotlin/JVM reference implementation, no Python parser, no independent spec, and .function calls make it Turing-complete	GFM read + a function-call surface rule
Djot	Engine	a clean formal grammar — the tractable one	frontier
LaTeX	Engine	write is a Typst-writer peer; read needs macro expansion (Turing-complete)	P11
docx	Engine	write is mechanical XML; read is style-heuristic and grade-varying	P12
wikitext	Engine	no grammar at all; the parser’s tree is flat, so a three-layer reader	P8, Tier 3
AsciiDoc, Org, man, Textile	Engine	own grammars, no compelling Python parser story yet	frontier, no work now
arbitrary web HTML	—	not a translation problem at all	refused (§P9)

The pattern worth naming, because it is the same problem three times. Quarkdown’s .function calls, MediaWiki’s {{templates}}, and LaTeX’s \macros are each a Turing-complete expansion layer living inside a document format. Evaluating any of them correctly requires the host environment — that wiki, that preamble, that standard library — which a translator does not have and should not pretend to.

myform’s answer is identical in all three cases, and it is P2:

1. Never expand. Not as a limitation — as a correctness position.

2. Always enclave. The construct is preserved verbatim, marked, and linked (§P2).

3. Optionally map a curated set of known shapes, per format, by configuration.

P2 was justified once, by wikitext. O3 has now justified it three times over, in formats that share nothing else. That is the strongest evidence available that ENCLAVE is a primitive rather than a workaround — and it is why P2 leading wave 1 was the right call independent of everything else in this document.

4. The graph past N=7: unequal investment, and an audit that must not grow quadratically

§1.1’s arithmetic — “four formats to seven takes 16 cells to 49” — had the right shape and the wrong horizon. §3.11 puts nine engines plausibly in scope, and P10’s dialects register through the very same Reader.register / Writer.register decorators, so each one lands in test_matrix_sweep.py at collection time too. Thirteen registered formats is 169 cells.

So the self-growing audit praised in §1.1 is also the thing most likely to become the slowest test in this repo, and the tier policy alone does not fix that: Tier 3 imposes no floor, but it still runs every cell it covers. Two rules, both cheap, both wanted before P10 registers its first dialect — retrofitting them after the sweep is slow is strictly worse:

• A dialect shares its base format’s audit. A Dialect declares its base engine; the sweep runs its full cross product over engines, and for dialects only the cells touching that dialect’s own distinguishing constructs. Pandoc-flavored need not be swept against Typst — GFM already was, and the delta is an extension tuple.

• Tier 3 is sampled, not exhaustive. Fixed-seed sampling across Tier-3 cells per run, with the exhaustive sweep behind a marker for CI and releases. test_matrix_sweep.py calls itself “an audit, not a correctness suite”; an audit is allowed to sample, and saying so keeps that docstring honest at N=13 rather than quietly abandoning it.

Three tiers, updated for O3:

Tier	Cells	Gate
1 — daily drivers (full correctness)	myst↔myst, gfm↔gfm, myst↔gfm, myst→html, obsidian↔myst	byte-level expectations; existing corpus suites in full force
2 — supported (coverage floor)	everything touching rst, typst, html-read, obsidian↔gfm, pandoc cells, latex-write, docx-write	audit-green and ≥95% content-weighted nativeness (P3)
3 — audited (no floor, sampled)	all wikitext cells, quarkdown, latex-read, docx-read, exotic pairs (typst→wikitext)	must not crash; must report honestly; coverage measured, not gated

A bold spec is credible when it says where it is not spending. This is that.

5. Constraints and tripwires

5.1. The import budget is a hard shape constraint, not a packaging detail

myform-spec.md §10 gates import myform at baseline + 20%, with a 0.216 s cold-start warn and a 0.432 s hard ceiling. Sphinx, myst-parser, furo, mwparserfromhell, python-docx, pylatexenc, and any HTML parser as dependencies would obliterate that outright.

Therefore: every proposal here ships as an optional extra with function-local imports, following the _DIRECT_WRITERS lazy-loading precedent already in myform/writers/__init__.py. This constrains the design of P5 (no import-time theme registry, no eager Collection scan), not merely its pyproject.toml entry.

O3 sharpens this from a rule into a selection criterion. §3.11’s Declaration band costs nothing at import time — a tuple and a table — while every Engine-band format brings a parser. That asymmetry is not incidental: it is why “add the flavors where we can do so easily” and “keep the import budget” turn out to be the same constraint read from two directions, and why P10 can absorb an arbitrary number of dialects without moving the number at all.

5.2. The published v1.0.0 extension surface

Capability (P2) and the writer/reader registries are public as of v1.0.0. P2’s enum addition wants a documented fallback and a minor-version bump — see D2.

5.3. README canonicality

test_cli__readme asserts the repository README formats to itself. Any change to the format table must survive myform’s own formatter — including sequential ordered-list numbering under --number.

5.4. Corpus couplings to cut, and who keeps the policy

mdsite.py imports corpus.ai_home (hardcoding ~/ai/site, ~/ai/scratch), corpus.cli_common, and corpus.typst (which shells the typst binary). Its fourth import, my.regex, is not a coupling to cut — my-basis>=1.0.0 is already a myform dependency per myform-spec.md §2.5, so RegexStore comes along in-family. A PyPI library cannot hardcode ~/ai — those are fleet-instance policy.

Recommendation (N-02, policy/mechanism): myform owns the mechanism — Collection, HTML, staging, search, serve — parameterized by config and CLI. Corpus keeps mdsite and myst-report as thin wrappers that supply the ~/ai roots, the Diátaxis journal/reports default, and the port. The commands keep working, the fleet policy stays where fleet policy belongs, and ~/my/corpus/skills/myst-reporting/SKILL.md needs only a light edit rather than a rewrite. Typst rendering becomes feature-detected and optional.

5.5. Three tripwires P7 hit, which every later dialect will hit too

All three were found by building or by hostile review, not by reasoning, and each is cheap once known and expensive once forgotten — which is what earns them a place here rather than in a commit message.

A capability table says one thing per node kind; some distinctions are per node. This is the tripwire that produced P7’s only critical defect, and it will recur for every dialect that partially supports a construct. Obsidian has callouts, not directives — so mystDirective is NATIVE for > [!tip] Title and not for {code-block} or for an admonition carrying :name:. A table cannot say that, and the writer’s NATIVE default meant it claimed all of them: unparsed bodies and unrendered options were deleted with an empty report, the exact failure this package exists to prevent.

Worse, the existing audit could not catch it. test_matrix_sweep.py’s AC4 check verifies that every non-NATIVE node produced a report entry — so a wrong NATIVE claim is unfalsifiable by construction, and the sweep’s MyST sample happened to contain only the admonition shape that works. A per-node distinction belongs in a register_preflight rule, never in the table, and a partially-supported construct is a signal to reach for one.

A built-in dialect self-registers only when its myform reader loads. mdformat.plugins eagerly imports every published mdformat.parser_extension and checks renderer conflicts across the installed set, even when a user did not enable that flavor. Obsidian deliberately has no distribution entry point: ObsidianReader imports register_obsidian_extension() after the dialect module exists, and that idempotent helper adds the name without displacing a real third-party plugin. If a different plugin already owns obsidian, myform leaves it registered and refuses its built-in reader with a diagnosed conflict; it never combines foreign parser semantics with the built-in writer contract. The myform API can therefore enable Obsidian without process-wide conflict warnings, while bare mdformat --extensions obsidian remains explicitly outside the contract.

The corpus format-on-edit hook is not dialect-aware. It runs the MyST formatter over every .md written through an agent’s edit tools, and MyST correctly escapes [[ — so an Obsidian test fixture silently becomes \[[Note]\] on write. Dialect fixtures must be written through a path the hook does not cover. This is a corpus-policy question rather than a myform defect (myform’s escaping is right), but P10 turns it from an annoyance into a recurring tax: every Extension-band flavor in §3.11 ships fixtures in a syntax the default formatter will fight.

6. Sizing, so the decisions below are answerable

Rough orders of magnitude, bracketed by what comparable modules already cost in this repo (writers/rst.py is 682 lines, writers/typst.py is 942, readers/rst.py is 792).

Proposal	Shape	New dependency	v1.0.0 surface
P1 HTML writer	1 module, ~700–900 lines + capability table + tests	none (stdlib)	additive
P2 ENCLAVE	enum + degrade/engine.py + lowerings.py + 1 emitter per target	none	breaking-ish — the only one
P3 coverage	1 module + 1 CLI verb + a pinned corpus	none	additive
P4 Collection	1 new model module + a resolve() pass beside lower() — smaller under D4 (no nav, no search); no writer edited	none	additive
P5 myform site	staging + conf.py/toctree generation + server; no theme, no search index, no JS — Sphinx and furo own those	sphinx, myst-parser, furo (myform[site] extra)	additive
P6 site new	folded into P5	none	—
P7 Obsidian	1 dialect pair + 1 markdown-it plugin (wikilinks, ==, %%, embeds) — Extension band, not free	none	additive
P8 wikitext	1 three-layer reader + 1 writer	mwparserfromhell (extra)	additive
P9 HTML reader	1 module	possibly none (stdlib html.parser)	additive
P10 dialect layer	naming an existing pattern + a spelling knob + the §4 sweep rules; then ~50 lines per Declaration-band flavor	none	additive
P11 LaTeX	1 writer (a writers/typst.py peer); reader bounded, macros → enclaves	pylatexenc for read (extra, unverified)	additive
P12 docx	1 writer (OOXML package); reader style-heuristic, grade-varying	python-docx (myform[docx] extra)	additive

Three things worth reading off that table. Every new dependency lives in an extra — myform[site], myform[wikitext], myform[docx], myform[latex] — and import myform never touches any of them, so §5.1’s budget holds by construction rather than by vigilance. (sphinx, myst-parser, and furo are already dev dependencies of this repo’s docs group, so P5’s extra promotes existing pins rather than adding new ones.) P2 remains the only proposal that touches the published surface, which is why D2 was the one decision that could not be deferred past the first wave — and O3 has since justified it twice more (§3.11). And the largest single item in the table is now P1, which is the other half of why O2 moved it out of wave 1: wave 1 is three mechanisms, none of them a rendering slog.

7. Decisions taken; nothing left open

7.1. Answered by the operator, 2026-08-05

ID	Decision
D1	Wave 1 = P1 + P2 + P4, with P7 (Obsidian) immediately after as proof a new format is now cheap. — amended by O2, below: P1 and P7 trade places, so wave 1 = P2 + P4 + P7 and wave 2 opens with P1 + P3. D1’s intent is preserved: P7 still lands immediately after P4.
D2	ENCLAVE ships additive in v1.1, with a documented CARRY fallback for writers unaware of it.
D3	MathML by default, delimiter-preserved spans configurable.
D4	Sphinx stays. myform translates into Sphinx; it does not replace it. §P5 rewritten; §P4 narrowed; §P2’s table reordered.
D5	Corpus mdsite/myst-report survive as thin wrappers holding the ~/ai policy (§5.4).
D6	Wikitext takes the easy win first — the * → wikitext writer ships ahead of the three-layer reader.

7.2. Follow-ups, answered 2026-08-05

ID	Resolution
O1	to-PDF and to-HTML are separate goals that only sometimes coincidentally share infrastructure. Recorded as §2.1 and applied to §P5, §P11, and §5.4. Neither terminal is a fallback for the other, and a linked artifact is a link — never an ENCLAVE.
O2	Delegated to the author. P1 and P7 trade wave slots (§P1). Wave 1 = P2 + P4 + P7; wave 2 opens P1 + P3, keeping P1 adjacent to its only dependent instead of idle for a wave. D1 amended above.
O3	LaTeX (P11) and docx (P12) promoted out of the frontier tier. Markdown flavors handled by P10, whose three cost bands make “where we can do so easily” a decidable question. §3.11 is the requested record of what needs specialized work, and why.

O1 is the one that changed a design rather than a schedule. The original §P5 proposed a per-document toggle between a translated page and a compiled artifact — which quietly assumed the two were alternatives competing on fidelity. They are not. Once they are named as separate goals, the toggle disappears: myform site builds a site, the PDF path builds PDFs, and a collection may be handed to both. A question that looked like it needed a feature turned out to need a distinction.

O3’s second half produced the most reusable finding in this revision. Asked to record what requires specialized work, §3.11 found that Quarkdown’s .function calls, MediaWiki’s {{templates}}, and LaTeX’s \macros are the same problem three times: a Turing-complete expansion layer inside a document format, evaluable only with the host environment a translator does not have. The answer is the same in all three — never expand, always enclave, optionally map known shapes. P2 was justified once by wikitext; it is now justified three times over by formats that share nothing else with it.

7.3. Nothing is open

D4 remains the consequential decision, and it improved the design. The argument that had motivated going native — Sphinx cannot read Typst, Obsidian, or wikitext — is answered better by translation than by replacement: myform converts them to MyST and Sphinx does what it has always done. Nothing is reimplemented, and the input set grows from two formats to seven, with §3.11’s ledger showing where the next six would come from and what each would cost.

8. Problem space

• The universal graph — D1–D6 and O1–O3 all answered; nothing open; wave 1 in motion ⭐

  • Wave 1 (D1, as amended by O2) — P2 + P4 + P7, in that dependency order ⭐

    • P2 ENCLAVE capability — the “safely demarcated and linked” primitive; v1.1 additive per D2; blocks P8, P11, and Quarkdown-read ✅

    • P4.1 Collection — landed: myform/collect, a resolve() pass beside lower(); no writer edited, identity without a collection, dangling refs in their own report ✅

      • P4.2 the label index — {ref}/{numref}/{eq} take a label, not a path, so P4.1 deliberately resolves {doc} only; labels need a second index and a second resolution kind 💤

  • P7 Obsidian dialect — promoted into wave 1 by O2; near-lossless against MyST; the first real exercise of resolve() ⏳

  • Wave 2 — the measurement pair, kept together 💤

    • P1 HTML writer — moved here by O2; P3’s ceiling and a standalone convert target; the to-HTML terminal at document scale (§2.1) 💤

    • P3 coverage instrument — needs P1’s ceiling; makes the 95% claim defensible or kills it; docx-read will stress its min(read, write) rule 💤

  • P10 dialect layer — names a pattern already built twice; three cost bands decide O3’s “easily”; needs §4’s sweep rules first 💤

    • Pandoc-flavored — the cheapest proof of P10; most constructs already have plugins 💤

    • Quarto, kramdown, MultiMarkdown, CommonMark-strict — near-free once Pandoc lands 💤

    • Quarkdown — write is nearly free (a GFM superset); read is GFM + a function-call rule, unknown functions enclaved 💤

  • P5 myform site — Sphinx-backed per D4; needs P4; deletes the massage stage; O1 removed its one design question 💤

  • P9 HTML reader — scoped to semantic HTML; open-web extraction explicitly refused 💤

  • P11 LaTeX / P12 docx — promoted by O3; both write-first, both read-bounded for structural reasons ⛔

  • P8 wikitext — writer first per D6; three-layer reader later; templates as enclaves; Tier 3 ⛔

  • Frontier (AsciiDoc, Org, man, Textile, Djot, EPUB) — architecture stays open; no work now. EPUB write inherits P1; Djot is the tractable engine ⛔

  • Repo metadata drift — README, pyproject.toml description, and the stale predecessor-spec pointer refreshed to v1.0.0 facts; myform-spec.md’s launch matrix marked superseded ✅

  • plane dialect — out-of-band, not a numbered P-proposal — operator-directed: a direct writer+reader pair for Plane’s Tiptap description_html, anti-idiomatic by design (exact vendor wire-shape, not semantic HTML) and architecturally closer to rst/typst’s direct model walk than to P10’s shared-markdown-engine dialects. Landed both steps (typed ListItem.checked primitive; the writer/reader themselves, registered in the standard matrix sweep). Deliberately not folded into P1/P9’s semantic-HTML scope, and not this document’s concern to migrate – corpus’s own call-site swap is a separate follow-up card ✅

Keystone: P7. With P2 and P4 both landed, wave 1’s remaining item is the Obsidian dialect — and it is now the load-bearing one, since it is what first exercises resolve() against a real format’s own reference syntax rather than against MyST’s. Its markdown-it plugin (wikilinks, ==highlight==, %%comment%%, ![[embed]]) is also the concrete template every later Extension-band flavor in §3.11 copies, so what P7 costs once, Pandoc and Quarto do not pay again.