docs(xml): describe the parser that enforces limits and builds the tree

docs/benchmarks.md

@@ -45,9 +45,10 @@ selected provider. Rejection cases check corrupted signature evidence and malfor
 XML on every backend, rather than interpreting an error as a successful operation.
 RSA-SHA256 sign/verify use the
 selected provider's actual key handle.
-Projection calls the production normalizer over a prepared backend DOM and lexical
-positions, without a second parser invocation. Differential parsing has no
-single-backend projection measurement. Graph compilation and execution are separate
+Projection calls the production normalizer over a prepared roxmltree DOM and lexical
+positions, without a second parser invocation. It is measured for roxmltree only:
+xmloxide builds the semantic arena as it parses, so its parse case covers that
+work, and differential parsing has no single-backend projection. Graph compilation and execution are separate
 synthetic fan-out measurements at 1/8/32/64 references, not substitutes for complete
 operation measurements. Typed policy validation/checks are measured independently;
 their cost must not be subtracted from an end-to-end result to claim an unsafe path.

docs/xml-backend-patches.md

@@ -51,15 +51,26 @@ of a replacement node arena solely to drop the consumed parser.
 
 The maintained construction kernels specialize storage without changing parser
 selection or grammar. Scoped reference replay pays raw parser state, DTD models,
-namespace indexes, source positions and the semantic arena with its current
-execution. DTD entity/default tables move into runtime state; entity fragments
-move node payloads while rebasing links instead of cloning recursive subtrees.
-Element and DTD-group parsing use bounded, paid continuation stacks. Diagnostic
-labels retain their allocation charges, and resource refusal is terminal rather
-than a malformed-input rejection or a reason to try another backend.
+namespace indexes and the semantic arena with its current execution. DTD
+entity/default tables move into runtime state. Element and DTD-group parsing use
+bounded, paid continuation stacks. Diagnostic labels retain their allocation
+charges, and resource refusal is terminal rather than a malformed-input
+rejection or a reason to try another backend.
 
-The backend adapters continue to use the shared lexical preflight and semantic
-arena. Backend selection does not introduce implicit fallback, a second ID
-resolver or an external entity acquisition path. Differential mode still
-compares the two semantic projections rather than choosing whichever parser
-accepts an input.
+The xmloxide parser is generic over the tree it writes to. xml-sec parses into
+the semantic arena directly, with no intermediate xmloxide DOM: the parser
+supplies every source range, and an entity's replacement text is read into the
+same tree, its nodes taking the outermost reference's range and remaining
+unactionable. A DOCTYPE is recognized only by its case-sensitive keyword
+(XML 1.0 production 28). When the text `<!DOCTYPE` occurs nowhere in the input,
+the parser itself enforces the node, depth and namespace limits as it reads.
+Any other input, including one that has the text only inside a comment or a
+CDATA section, first passes the strict lexical scan that bounds a DOCTYPE's
+declarations and entity expansion; that path is stricter, never weaker.
+
+roxmltree builds its own DOM, which is projected into the same semantic arena
+through the source positions the lexical scan records; positions are recorded
+only for a backend that reads them. Backend selection does not introduce
+implicit fallback, a second ID resolver or an external entity acquisition path.
+Differential mode still compares the two semantic trees rather than choosing
+whichever parser accepts an input.

docs/xmldsig.md

@@ -497,8 +497,11 @@ certificates provide key material and do not become trusted merely because they
 certificate is present in both pools, its explicit trusted classification is retained.
 `ResourcePolicy::max_xml_document_bytes` rejects verification and signing inputs before DOM
 parsing; the same immutable ceiling is rechecked after signing mutations that enlarge the XML.
-The selected node and depth ceilings are enforced by a streaming preflight before either parser
-backend allocates a DOM, then rechecked on every staged copy, adapter parse, and committed generation.
+The selected node, depth and namespace-binding ceilings are enforced before the node that would
+exceed them is stored: an xmloxide parse of an input that contains no `<!DOCTYPE` text counts
+them as it reads, while any other input, and every roxmltree or differential parse, passes one
+strict lexical scan that checks them before the parser runs. They are rechecked on every staged copy,
+adapter parse, and committed generation.
 `ResourcePolicy::max_xml_parse_work_bytes` separately bounds cumulative parser work across the
 whole operation. Initial parsing, generated-template validation, binary-to-node-set adapters,
 staged copies, digest dependency levels, Manifest recursion, and committed generations all charge

docs/xmlenc.md

@@ -298,9 +298,11 @@ AES-GCM.
 Use `decrypt_document` to replace one typed `EncryptedData` in a complete XML string. Pass its
 `Id` when the document contains multiple encrypted regions. The compiled decryption policy checks
 the shared `ResourcePolicy::max_xml_document_bytes` ceiling before DOM allocation and applies its
-XML node and depth ceilings to the initial document and every replacement generation. A bounded
-streaming preflight enforces these limits before either parser backend allocates a DOM and charges
-recursive internal-entity replacement traversal to cumulative XML parse work.
+XML node, depth and namespace-binding ceilings to the initial document and every replacement
+generation. A refusal comes before the node that exceeds them is stored: an xmloxide parse of an
+input that contains no `<!DOCTYPE` text checks them as it reads, and any other parse passes one
+strict lexical scan first, which also charges recursive internal-entity replacement traversal to
+cumulative XML parse work.
 `encrypt_owned_document` and
 `decrypt_owned_document` reuse the retained parsed view, validate replacement XML in the parent
 namespace context, and invalidate prior node identities after a successful mutation. String APIs