fragment-selectors: add xpathEntries DTO for backend use (Phase 3)

Walk a parsed instance once and return a flat, JSON-serializable array of every
present leaf as `XPathEntry { Path; XPath; Value }`, with real array positions
taken from the data. Quotations can't cross a network boundary, so this is the
backend-facing counterpart to xpathOf/xpointerOf.

- XPathEntry record (public, in the BioFSharp.IO.INSDC namespace) + the
  xpathEntries object-graph walk in XPathTracking.fs; returns an array (not an
  F# list) so it serializes cleanly under System.Text.Json / Newtonsoft.
- xpathEntries wrapper on all eight IO entity modules.
- tests: scalar/attribute/positional-collection leaves, in-document resolution,
  and unique non-empty xpaths.
- plans/xml-fragment-selectors.md: Phase 3 section.

Author: kMutagene

plans/xml-fragment-selectors.md

@@ -206,6 +206,35 @@ obsolete.
 - An out-of-range collection index raises a clear exception (the index is validated against the
   instance).
 
+## Phase 3 — serializable per-instance DTO (`xpathEntries`)
+
+For backend/API use a quotation can't cross the wire, so Phase 3 walks a parsed instance once and
+returns a flat, JSON-serializable array of every present leaf:
+
+```fsharp
+type XPathEntry = { Path: string; XPath: string; Value: string }
+
+project |> BioProject.xpathEntries
+//  [ { Path = "Accession"; XPath = "/PROJECT/@accession"; Value = "PRJDB5192" }
+//    { Path = "Name";      XPath = "/PROJECT/NAME";        Value = "Arabidopsis ..." }
+//    { Path = "Identifiers.SecondaryId[0].Value"
+//      XPath = "/PROJECT/IDENTIFIERS/SECONDARY_ID[1]/text()"; Value = "DRP003416" } ... ]
+```
+
+- **Walk, not quotation:** reuses the Phase-2 attribute→step mapping but traverses the whole object
+  graph, emitting one entry per leaf with real array positions and only the nodes actually present
+  (choice groups resolve to the populated branch for free).
+- **Shape:** a flat `XPathEntry[]` (a plain record, no JSON-library coupling) — the simplest complete
+  form. A hierarchical tree or a `path → xpath` overlay is a pure projection of it, deferred unless
+  needed. Returns an **array**, not an F# list, so it serializes cleanly under System.Text.Json /
+  Newtonsoft.
+- **Fields:** `Path` is the F# property path with positions (`Identifiers.SecondaryId[0].Value`,
+  0-based); `XPath` is the bare absolute XPath; `Value` is the leaf's string form (equals the source
+  XML text for strings — enum/date leaves use the invariant CLR form, which can differ from the raw
+  serialized text).
+- **Files:** `xpathEntries` + the public `XPathEntry` record in `XPathTracking.fs` (the type in the
+  `BioFSharp.IO.INSDC` namespace), plus a one-line wrapper on each entity module.
+
 ## Out of scope
 
 - No CSV/RFC-7111 selectors — XML only.

src/BioFSharp.IO.INSDC/Analysis.fs

@@ -31,3 +31,8 @@ module Analysis =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (analysis: Analysis) : string =
         XPathTracking.xpointerOf selector analysis
+
+    /// Every present leaf of a parsed `analysis` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (analysis: Analysis) : XPathEntry[] =
+        XPathTracking.xpathEntries analysis

src/BioFSharp.IO.INSDC/BioProject.fs

@@ -34,3 +34,8 @@ module BioProject =
     /// `project |> BioProject.xpointerOf <@ fun p -> p.Name @>` -> `#xpointer(/PROJECT/NAME)`.
     let xpointerOf selector (project: BioProject) : string =
         XPathTracking.xpointerOf selector project
+
+    /// Every present leaf of a parsed `project` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (project: BioProject) : XPathEntry[] =
+        XPathTracking.xpathEntries project

src/BioFSharp.IO.INSDC/BioSample.fs

@@ -33,3 +33,8 @@ module BioSample =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (sample: BioSample) : string =
         XPathTracking.xpointerOf selector sample
+
+    /// Every present leaf of a parsed `sample` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (sample: BioSample) : XPathEntry[] =
+        XPathTracking.xpathEntries sample

src/BioFSharp.IO.INSDC/Experiment.fs

@@ -31,3 +31,8 @@ module Experiment =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (experiment: Experiment) : string =
         XPathTracking.xpointerOf selector experiment
+
+    /// Every present leaf of a parsed `experiment` as an `XPathEntry` (property path, positional
+    /// XPath, value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (experiment: Experiment) : XPathEntry[] =
+        XPathTracking.xpathEntries experiment

src/BioFSharp.IO.INSDC/Internal/XPathTracking.fs

@@ -1,3 +1,14 @@
+namespace BioFSharp.IO.INSDC
+
+/// A single leaf of a parsed INSDC record: its F# property path (with array positions), the absolute
+/// positional XPath to the value in the source XML, and the value as a string. A plain serializable
+/// record for web/API DTOs — one per present leaf of a parsed entity, position-qualified.
+type XPathEntry =
+    { Path: string
+      XPath: string
+      Value: string }
+
+
 namespace BioFSharp.IO.INSDC.Internal
 
 open System
@@ -9,6 +20,8 @@ open System.Xml.Serialization
 
 open Microsoft.FSharp.Quotations
 
+open BioFSharp.IO.INSDC
+
 /// Resolves the concrete, position-qualified XPath of a property on a parsed INSDC value. Public
 /// entity modules expose this as `<Entity>.xpathOf` (the bare XPath) and `<Entity>.xpointerOf` (the
 /// same path wrapped as a W3C `#xpointer(...)` fragment). The property is named with a quotation
@@ -132,3 +145,48 @@ module XPathTracking =
     /// The same selector as `xpathOf`, wrapped as a W3C XPointer fragment (`#xpointer(/PROJECT/NAME)`).
     let xpointerOf (selector: Expr<'Root -> 'P>) (root: 'Root) : string =
         "#xpointer(" + xpathOf selector root + ")"
+
+    /// True for a model class to descend into (vs. a leaf: string, primitive, enum, DateTime, ...).
+    let private isModelClass (modelAsm: Assembly) (t: Type) : bool =
+        t.IsClass && t <> typeof<string> && t.Assembly = modelAsm
+
+    /// The string form of a leaf value. Equals the source XML text for strings; enum/date leaves use
+    /// the invariant CLR form, which can differ from the raw serialized text.
+    let private stringify (v: obj) : string =
+        match v with
+        | null -> null
+        | :? string as s -> s
+        | :? bool as b -> if b then "true" else "false"
+        | :? IFormattable as f -> f.ToString(null, System.Globalization.CultureInfo.InvariantCulture)
+        | other -> other.ToString()
+
+    /// Walk a parsed `root` value and return one `XPathEntry` per present leaf, with array positions
+    /// (`COLLABORATOR[2]`) taken from the data — a serializable, position-qualified view of the whole
+    /// record for use in DTOs. Containers are not emitted; only addressable leaf values.
+    let xpathEntries (root: 'Root) : XPathEntry[] =
+        let modelAsm = typeof<'Root>.Assembly
+        let acc = ResizeArray<XPathEntry>()
+        let appendKey prefix seg = if prefix = "" then seg else prefix + "." + seg
+        let rec emit (key: string) (xpath: string) (value: obj) (depth: int) =
+            if not (isNull value) then
+                if isModelClass modelAsm (value.GetType()) then walk key xpath value (depth + 1)
+                else acc.Add { Path = key; XPath = xpath; Value = stringify value }
+        and walk (keyPrefix: string) (xpathPrefix: string) (node: obj) (depth: int) =
+            if not (isNull node) && depth <= 64 then
+                node.GetType().GetProperties(BindingFlags.Public ||| BindingFlags.Instance)
+                |> Array.filter (fun p -> p.CanRead && p.GetIndexParameters().Length = 0)
+                |> Array.iter (fun p ->
+                    match relativeStep p with
+                    | None -> ()
+                    | Some(piece, repeatable) ->
+                        let value = p.GetValue node
+                        if not (isNull value) then
+                            if repeatable then
+                                items value
+                                |> Array.iteri (fun i item ->
+                                    emit (appendKey keyPrefix (sprintf "%s[%d]" p.Name i))
+                                         (xpathPrefix + "/" + withIndex piece i) item depth)
+                            else
+                                emit (appendKey keyPrefix p.Name) (xpathPrefix + "/" + piece) value depth)
+        walk "" ("/" + rootElementName typeof<'Root>) (box root) 0
+        acc.ToArray()

src/BioFSharp.IO.INSDC/Receipt.fs

@@ -32,3 +32,8 @@ module Receipt =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (receipt: Receipt) : string =
         XPathTracking.xpointerOf selector receipt
+
+    /// Every present leaf of a parsed `receipt` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (receipt: Receipt) : XPathEntry[] =
+        XPathTracking.xpathEntries receipt

src/BioFSharp.IO.INSDC/Run.fs

@@ -31,3 +31,8 @@ module Run =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (run: Run) : string =
         XPathTracking.xpointerOf selector run
+
+    /// Every present leaf of a parsed `run` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (run: Run) : XPathEntry[] =
+        XPathTracking.xpathEntries run

src/BioFSharp.IO.INSDC/Study.fs

@@ -31,3 +31,8 @@ module Study =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (study: Study) : string =
         XPathTracking.xpointerOf selector study
+
+    /// Every present leaf of a parsed `study` as an `XPathEntry` (property path, positional XPath,
+    /// value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (study: Study) : XPathEntry[] =
+        XPathTracking.xpathEntries study

src/BioFSharp.IO.INSDC/Submission.fs

@@ -31,3 +31,8 @@ module Submission =
     /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
     let xpointerOf selector (submission: Submission) : string =
         XPathTracking.xpointerOf selector submission
+
+    /// Every present leaf of a parsed `submission` as an `XPathEntry` (property path, positional
+    /// XPath, value) — a serializable, position-qualified DTO of the whole record for a web API.
+    let xpathEntries (submission: Submission) : XPathEntry[] =
+        XPathTracking.xpathEntries submission