# Research first (when stuck, read the source and the literature)

PureXML reimplements, in pure Swift, behavior that mature C/Java/C#/Python
libraries already get right. When a spec point is ambiguous, an algorithm is
unclear, a test disagrees with your reasoning, or you are about to guess: stop
and consult sources before writing code. Guessing at a standard's corner case is
how this engine accrues silent bugs. Reading the reference is how it stops.

This is mandatory, in order:

1. **Look in the research repo first.** The private `PureXML-research` repo
   vendors reference implementations and analysis for exactly this purpose:
   `libraries/` (libxml2, Xerces-J, Xerces-C, .NET `System.Xml.Schema`, Python
   `xmlschema`, and others), `notes/` (prior clean-room write-ups), and the W3C
   conformance suites. Find the matching routine and read it. The authoritative
   algorithm is almost always already on disk. (Example: the MapAndSum
   particle-restriction rule was fixed by reading Xerces `XSConstraints.java`,
   after three incremental guesses had regressed ~30 cases.)

2. **If the needed reference is not there, vendor it.** If no library in
   `PureXML-research/libraries/` covers the area, add one (use the repo's
   `scripts-vendor.sh` / vendoring convention). Pick a permissively licensed,
   widely deployed implementation. Record it in the research repo's attribution.

3. **If what is there is not enough, find more.** One implementation can be
   wrong, stubbed, or lenient (libxml2 stubs particle-restriction; Microsoft and
   Xerces disagree on spec-ambiguous points). When implementations disagree or
   under-specify, gather more of them and compare; the W3C test metadata often
   states which reading is intended.

4. **Always consult the scientific and standards literature.** Read the W3C
   Recommendation text itself (it is the spec, not a library's interpretation),
   its errata, and the academic literature for the underlying algorithm
   (content-model determinism / Glushkov and position automata, Brzozowski
   derivatives, regular-language subset and ambiguity, schema composition). The
   research repo's `references/` and `notes/` collect these; extend them.

## Clean-room discipline (non-negotiable)

The research sources are for **study, not copying**. PureXML stays pure Swift,
dependency-free, Linux- and WASI-compatible (see `AGENTS.md`). Never copy C,
Java, C#, JavaScript, or any non-Swift source into the public package. Extract
the *algorithm and the invariants* from the reference, then implement them from
first principles in Swift. Keep attribution accurate where compatibility work
references a project.

## What counts as "stuck"

Not only a dead end. Any of: a corner case you cannot derive with certainty from
the spec; a conformance test whose expected result contradicts your reasoning;
an occurrence/namespace/derivation rule you are about to special-case by feel; a
choice between two plausible interpretations. In all of these, the reference and
the literature decide, not intuition. Disclose the source you used.