docs(xml): document and pin the processing-instruction position limit (#2202)

Rule-14 sweep. The ticket's recorded gate named "/rv is ABSENT" and
"consumers were not inspected", both stale -- but neither was ever the real
gate. The real one is the vendored substrate, and it stands. What was
actually outstanding is this ticket's OWN acceptance criteria, whose fallback
path needs no approval and had simply never been executed: "if the substrate
cannot express it, the correct outcome is an explicit documented limitation
on XProcessingInstruction and XmlWriter::WriteProcessingInstruction plus a
pin, not silence."

No production statement changed. This is a declaration and its evidence, the
shape of #2015 and #2324.

This runtime writes a PI correctly in any position and reads one back only
before every other node -- an XML declaration may precede it and nothing else
may, not even a comment -- so SR-AUD-349's closure property does not hold for
this one node kind.

The cause is re-measured directly rather than asserted: called with no port
code involved, vendor/tinyxml2 produces exactly the port's five verdicts, and
the leading "<?p d?>" comes back as a Declaration node valued "p d".
tinyxml2 has no processing-instruction node type at all, so every "<?"
inherits the rule that a declaration may appear only before anything else.
The fifth row is new evidence this ticket adds: a declaration MAY precede the
PI, so the rule is "before every other node" rather than "first token", and
that is now pinned.

.NET differs by exactly that model distinction -- XmlLoader.cs:203-209
switches on XmlDeclaration and ProcessingInstruction as separate cases in the
same general node loop, which runs for element content too.

Both repair routes are refused, the second now priced by measurement rather
than judgement: patching vendor/ is forbidden, and pre-rewriting non-leading
"<?...?>" around the substrate forks its semantics for every document --
mutation M3 implements a naive version and it breaks the shipped
XPathSelectTests.ProcessingInstructionNodeTest_SelectsPI.

Three mutations, all caught, two of them also by pre-existing tests. Pinned
at both layers as the criteria require; the asymmetry pin is written to fail
the moment the limitation lifts, naming both doc-comments.

Gate: 17,424 run, 17,424 passed, 0 failed, 0 skipped across 38 executables
(+3 on 17,421; SharpRuntimeTests_Xml 515 -> 518; no other executable moved).

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,112 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Declaration — a processing instruction can be read back only before every other node (ticket #2202)
+
+*2026-08-19.* This runtime writes a processing instruction correctly in any position and can
+parse one back **only at the very start of the document**. That asymmetry is now documented at
+both doors and pinned at both layers.
+
+**This ticket changed no production statement.** It is a declaration and its evidence, the same
+shape as #2015 and #2324. Nothing you can write, read or emit behaves differently.
+
+---
+
+## 1. The limitation
+
+| Document | Loads? |
+|---|---|
+| `<?p d?><root/>` | **yes** |
+| `<?xml version="1.0"?><?p d?><root/>` | **yes** — an XML declaration may precede it |
+| `<root><?p d?></root>` | no — `XML_ERROR_PARSING_DECLARATION` |
+| `<root/><?p d?>` | no |
+| `<!--c--><?p d?><root/>` | no — not even a comment may precede it |
+
+Both writer families — `System::Xml::XmlWriter::WriteProcessingInstruction` and
+`System::Xml::Linq::XProcessingInstruction` — emit the instruction in **every** one of those
+positions, and the text they emit is well-formed XML. So SR-AUD-349's closure property (whatever
+this runtime writes, this runtime must be able to read) does **not** hold for this one node kind.
+
+## 2. The cause is the substrate's node-type model
+
+Not a check in the wrong place, and not a defect in the port. Measured directly against
+`vendor/tinyxml2`, with no port code involved
+(`build-probe/2202_probe1_tinyxml2_direct.cpp`):
+
+```
+<?p d?><root/>                      -> OK
+<root><?p d?></root>                -> XML_ERROR_PARSING_DECLARATION
+<root/><?p d?>                      -> XML_ERROR_PARSING_DECLARATION
+<!--c--><?p d?><root/>              -> XML_ERROR_PARSING_DECLARATION
+<?xml version="1.0"?><?p d?><root/> -> OK
+first node of '<?p d?><root/>': Declaration=1 Unknown=0 Element=0 value=p d
+```
+
+Exactly the verdicts the port produces, and the last line is the reason: **tinyxml2 has no
+processing-instruction node type at all.** Every `<?` becomes an `XMLDeclaration` — the leading
+`<?p d?>` is a *Declaration* whose value is the string `p d` — so ordinary PIs inherit tinyxml2's
+rule that a declaration is allowed only at document level and before anything else.
+
+The port therefore neither loses nor rebases position information. There is no local projection
+bug to repair.
+
+## 3. .NET has no such limitation, and the difference is the same model distinction
+
+`XmlLoader.cs:203-209` switches on `XmlNodeType.XmlDeclaration` and
+`XmlNodeType.ProcessingInstruction` as **separate cases in the same general node loop** — a loop
+that runs for element content, not only for the prolog. Two node types, two rules. tinyxml2 has
+one node type and therefore one rule.
+
+## 4. Why it is documented rather than repaired
+
+Two routes exist and both are refused:
+
+1. **Patch `vendor/tinyxml2` to add a PI node type.** `vendor/` is third-party source, kept
+   unmodified from upstream, and CLAUDE.md forbids editing it.
+2. **Pre-rewrite non-leading `<?...?>` before handing text to the substrate and map it back.**
+   This forks the substrate's parsing semantics for every document that passes through
+   `LoadXml`, to serve one node kind. Measured as mutation M3 (§5), a naive version of exactly
+   this shim breaks `XPathSelectTests.ProcessingInstructionNodeTest_SelectsPI` — shipped,
+   working functionality — which is what a semantics fork costs in practice.
+
+The ticket's own acceptance criteria prescribe this outcome: *"if the substrate cannot express
+it, the correct outcome is an explicit documented limitation on `XProcessingInstruction` and
+`XmlWriter::WriteProcessingInstruction` plus a pin, not silence."* The substrate cannot express
+it, and that had been confirmed; the documentation and the second pin were simply never written.
+
+## 5. Evidence
+
+Three mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| M1 — the writer silently drops a PI written inside an element | `Decl2202_TheWriterEmitsWhatTheParserCannotReadBack` |
+| M2 — `LoadXml` swallows the substrate's parse error | both new pins **and four pre-existing tests** |
+| M3 — strip non-leading PIs before parsing (the realistic future "repair") | both new pins **and `XPathSelectTests.ProcessingInstructionNodeTest_SelectsPI`** |
+
+Pins, at both layers as the acceptance criteria require:
+
+* `System::Xml` — `XmlWriterValidationTests.Decl2202_*` (three cases, **new**: the four verdicts,
+  the declaration exception, and the write-then-fail-to-read asymmetry end to end).
+* `System::Xml::Linq` —
+  `XLinqLexicalSerializationTests.ProcessingInstruction_ParserPositionLimitIsSubstrateNotSerialization`
+  (pre-existing).
+
+Doc-comments: `XmlWriter::WriteProcessingInstruction` and `XProcessingInstruction`, both stating
+the limitation, its cause, and that .NET does not share it.
+
+Gate: **17,424 run, 17,424 passed, 0 failed, 0 skipped** across 38 executables — `+3` on 17,421,
+exactly the three new cases (`SharpRuntimeTests_Xml` 515 → 518). No other executable moved.
+
+## 6. What would reopen this
+
+A substrate with a real processing-instruction node type, or an upstream tinyxml2 that grows one.
+The asymmetry pin is written so it fails the moment the limitation lifts:
+
+> *"if this stops throwing, #2202's limitation is gone and the note on
+> `WriteProcessingInstruction` and `XProcessingInstruction` must be removed"*
+
+## 7. Downstream
+
+No behaviour changed, so nothing downstream can break. Neither `cna` nor `mobile-eggbert` was
+modified.

docs/Migration-XmlProcessingInstructionPositionLimit.md

@@ -26,6 +26,25 @@ namespace System::Xml::Linq {
      * matching real .NET's `XmlEncodedRawTextWriter.WriteCommentOrPi`. Before #2196 the direct
      * door emitted the raw `?>`, which closed the instruction early and made the resulting text
      * unparseable — this node kind is the one whose corruption was not silent.
+     *
+     * @note **This runtime cannot parse back a processing instruction placed anywhere except
+     * before every other node.** Serialization is correct in every position and the text is
+     * well-formed XML, but `XDocument::Parse` accepts a PI only at the very start of the
+     * document — an XML declaration may precede it, and nothing else may, not even a comment.
+     * `<root><?p d?></root>`, `<root/><?p d?>` and `<!--c--><?p d?><root/>` all throw.
+     *
+     * The cause is the vendored substrate's node-type model rather than anything in this port:
+     * `vendor/tinyxml2` has no processing-instruction type, so every `<?` becomes an XML
+     * *declaration* and inherits the rule that a declaration may appear only at document level
+     * and before anything else. `vendor/` is third-party source and is never edited.
+     *
+     * **.NET has no such limitation** — its loader handles `XmlNodeType.XmlDeclaration` and
+     * `XmlNodeType.ProcessingInstruction` as separate cases in the same general node loop
+     * (`XmlLoader.cs:203-209`), which runs for element content too.
+     *
+     * Ticket **#2202**; pinned by
+     * `XLinqLexicalSerializationTests.ProcessingInstruction_ParserPositionLimitIsSubstrateNotSerialization`
+     * and, at the `System::Xml` layer, by `XmlWriterValidationTests.Decl2202_*`.
      */
     class XProcessingInstruction : public XNode {
         std::string target_;

modules/xml-linq/include/System/Xml/Linq/XProcessingInstruction.hpp

@@ -139,6 +139,31 @@ namespace System::Xml {
          * @throws System::Xml::XmlException if @p target is not a valid XML name.
          * @throws System::ArgumentException if @p target is empty.
          * @throws System::InvalidOperationException if @c Close() has already been called.
+         *
+         * @note **This runtime cannot read back a processing instruction it writes anywhere
+         * except before every other node.** The instruction is emitted correctly in any
+         * position and is well-formed XML, but this runtime's own parser accepts one only at
+         * the very start of the document — an XML declaration may precede it, and nothing
+         * else may, not even a comment. `<root><?p d?></root>`, `<root/><?p d?>` and
+         * `<!--c--><?p d?><root/>` all fail to load. So SR-AUD-349's closure property —
+         * whatever this writer emits, this module's reader must consume — does **not** hold
+         * for this one node kind.
+         *
+         * This is a limitation of the vendored substrate's node-type model, not a check in
+         * the wrong place: `vendor/tinyxml2` has no processing-instruction type at all, so
+         * every `<?` becomes an XML *declaration* and inherits the rule that a declaration is
+         * allowed only at document level and before anything else. `vendor/` is third-party
+         * source and is never edited, and pre-rewriting non-leading `<?...?>` around the
+         * substrate would fork its semantics for every document.
+         *
+         * **.NET has no such limitation**, because its model separates the two: its loader
+         * switches on `XmlNodeType.XmlDeclaration` and `XmlNodeType.ProcessingInstruction` as
+         * distinct cases in the same general node loop (`XmlLoader.cs:203-209`), which runs
+         * for element content and not only for the prolog.
+         *
+         * Ticket **#2202**; pinned by `XmlWriterValidationTests.Decl2202_*` and, at the
+         * Xml.Linq layer, by
+         * `XLinqLexicalSerializationTests.ProcessingInstruction_ParserPositionLimitIsSubstrateNotSerialization`.
          */
         void WriteProcessingInstruction(const std::string& target, const std::string& data);
 

modules/xml/include/System/Xml/XmlWriter.hpp

@@ -784,3 +784,64 @@ TEST(XmlWriterValidationTests, Fix2348_TheCheckIsQuoteAware) {
                      System::Xml::XmlException);
     }
 }
+
+// ===========================================================================================
+// #2202 — the parser accepts a processing instruction ONLY before every other node.
+//
+// This is a DOCUMENTED LIMITATION, not a repair, and it is pinned at this layer because the
+// ticket's acceptance criteria ask for it "at both layers" and only the Xml.Linq layer had it
+// (XLinqLexicalSerializationTests.ProcessingInstruction_ParserPositionLimitIsSubstrateNotSerialization).
+//
+// THE ASYMMETRY: both of this runtime's writer families emit a PI in any position, and this
+// runtime's own parser can then read back only the leading one. SR-AUD-349's closure property
+// -- whatever the writer emits, the reader must consume -- does not hold for this node kind.
+//
+// THE CAUSE IS THE SUBSTRATE'S NODE-TYPE MODEL, not a misplaced check and not a defect in the
+// port. vendor/tinyxml2 has NO processing-instruction node type at all: every "<?" becomes an
+// XMLDeclaration, so tinyxml2's rule that a declaration is allowed only at document level and
+// before anything else catches ordinary PIs too. Called directly, with no port code involved,
+// tinyxml2 produces exactly the four verdicts below. vendor/ is third-party source and is never
+// edited (CLAUDE.md), and the alternative -- rewriting non-leading "<?...?>" before handing text
+// to the substrate and mapping it back -- forks the substrate's semantics for every document.
+//
+// .NET HAS NO SUCH LIMITATION, and the reason is precisely the model difference: its loader
+// switches on XmlNodeType.XmlDeclaration and XmlNodeType.ProcessingInstruction as SEPARATE
+// cases in the same general node loop (XmlLoader.cs:203-209), which runs for element content,
+// not only the prolog.
+// ===========================================================================================
+
+TEST(XmlWriterValidationTests, Decl2202_TheParserAcceptsAPiOnlyBeforeEveryOtherNode) {
+    const auto parses = [](const std::string& xml) {
+        System::Xml::XmlDocument doc;
+        doc.LoadXml(xml);
+    };
+    EXPECT_NO_THROW(parses("<?p d?><root/>"));
+    EXPECT_THROW(parses("<root><?p d?></root>"), XmlException);
+    EXPECT_THROW(parses("<root/><?p d?>"), XmlException);
+    // Not even a comment may precede it -- which is what shows the rule is "before every other
+    // node" rather than "outside the root element".
+    EXPECT_THROW(parses("<!--c--><?p d?><root/>"), XmlException);
+}
+
+TEST(XmlWriterValidationTests, Decl2202_AnXmlDeclarationMayStillPrecedeThePi) {
+    // The one node that may come first, because the substrate's single "<?" node type is the
+    // declaration. Recorded so the rule above is not read as stricter than it is.
+    System::Xml::XmlDocument doc;
+    EXPECT_NO_THROW(doc.LoadXml("<?xml version=\"1.0\"?><?p d?><root/>"));
+}
+
+TEST(XmlWriterValidationTests, Decl2202_TheWriterEmitsWhatTheParserCannotReadBack) {
+    // The asymmetry itself, asserted end to end rather than inferred from the two halves.
+    auto w = NewWriter();
+    w->WriteStartElement("root");
+    ASSERT_NO_THROW(w->WriteProcessingInstruction("p", "d"));
+    w->WriteEndElement();
+    const std::string emitted = w->ToString();
+    EXPECT_NE(emitted.find("<?p d?>"), std::string::npos)
+        << "the writer must still emit the instruction: " << emitted;
+
+    System::Xml::XmlDocument doc;
+    EXPECT_THROW(doc.LoadXml(emitted), XmlException)
+        << "if this stops throwing, #2202's limitation is gone and the note on "
+           "WriteProcessingInstruction and XProcessingInstruction must be removed";
+}