fragment-selectors: split xpathOf (bare XPath) from xpointerOf (#xpointer)

xpathOf now returns the bare absolute XPath (`/PROJECT/NAME`); the new
xpointerOf wraps the same path as a W3C `#xpointer(...)` fragment. Added
xpointerOf alongside xpathOf on all eight IO entity modules, and updated the
tests and the Phase 2 plan section to match.

Author: kMutagene

plans/xml-fragment-selectors.md

@@ -138,11 +138,14 @@ model. Phase 2 adds the runtime counterpart — given a value returned by `*.rea
 ```fsharp
 let project = BioProject.read "PRJDB5192.xml" |> Seq.head
 project |> BioProject.xpathOf <@ fun b -> b.Name @>
-//  -> "#xpointer(/PROJECT/NAME)"
-project |> BioProject.xpathOf <@ fun b -> b.Collaborators.[1].Name @>
+//  -> "/PROJECT/NAME"
+project |> BioProject.xpointerOf <@ fun b -> b.Collaborators.[1].Name @>
 //  -> "#xpointer(/PROJECT/COLLABORATORS/COLLABORATOR[2]/NAME)"
 ```
 
+Each entity exposes two functions: **`xpathOf`** returns the bare absolute XPath; **`xpointerOf`**
+wraps the same path as a W3C `#xpointer(...)` fragment.
+
 Where the Phase-1 maps describe where a property lives *structurally* (a `COLLABORATOR` node-set),
 Phase 2 returns the XPath of *this value in this document*: real array indices, only the nodes
 actually present, and xscgen choice groups resolved to the populated branch.
@@ -184,10 +187,10 @@ obsolete.
    Reflects over the FileFormats model types (the IO project already references FileFormats). It
    re-implements the attribute→step logic from `FragmentSelectorTasks.fs` (which is build-only); the
    duplication is factorable later but not worth blocking on.
-5. **Per-entity `xpathOf` — the `BioProject`/`Study`/`BioSample`/`Experiment`/`Run`/`Analysis`/
-   `Submission`/`Receipt` modules.** One-line wrappers over the generic core so `BioProject.xpathOf`
-   reads as in the example. `read`/`readString`/`write` are untouched — the IO read/write surface is
-   unchanged.
+5. **Per-entity `xpathOf` / `xpointerOf` — the `BioProject`/`Study`/`BioSample`/`Experiment`/`Run`/
+   `Analysis`/`Submission`/`Receipt` modules.** One-line wrappers over the generic core so
+   `BioProject.xpathOf` / `BioProject.xpointerOf` read as in the example. `read`/`readString`/`write`
+   are untouched — the IO read/write surface is unchanged.
 
 > **Scope note.** Phase 2 adds files to the **IO layer**, which Phase 1 excluded ("No IO-layer
 > changes"). It is the promotion of the Phase-1 "evaluate selector" follow-up into scope — but it stays

src/BioFSharp.IO.INSDC/Analysis.fs

@@ -22,8 +22,12 @@ module Analysis =
     let writeString (analysis: Analysis) : string =
         XmlSerializer.writeString analysis
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `analysis`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `analysis`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `analysis |> Analysis.xpathOf <@ fun a -> a.Files.[0].Filename @>`.
     let xpathOf selector (analysis: Analysis) : string =
         XPathTracking.xpathOf selector analysis
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (analysis: Analysis) : string =
+        XPathTracking.xpointerOf selector analysis

src/BioFSharp.IO.INSDC/BioProject.fs

@@ -24,8 +24,13 @@ module BioProject =
     let writeString (project: BioProject) : string =
         XmlSerializer.writeString project
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `project`. Name the property with a quotation, addressing array positions with `.[i]`:
-    /// `project |> BioProject.xpathOf <@ fun p -> p.Name @>` -> `#xpointer(/PROJECT/NAME)`.
+    /// Resolve the absolute XPath of a property of a parsed `project`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
+    /// `project |> BioProject.xpathOf <@ fun p -> p.Name @>` -> `/PROJECT/NAME`.
     let xpathOf selector (project: BioProject) : string =
         XPathTracking.xpathOf selector project
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector:
+    /// `project |> BioProject.xpointerOf <@ fun p -> p.Name @>` -> `#xpointer(/PROJECT/NAME)`.
+    let xpointerOf selector (project: BioProject) : string =
+        XPathTracking.xpointerOf selector project

src/BioFSharp.IO.INSDC/BioSample.fs

@@ -24,8 +24,12 @@ module BioSample =
     let writeString (sample: BioSample) : string =
         XmlSerializer.writeString sample
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `sample`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `sample`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `sample |> BioSample.xpathOf <@ fun s -> s.SampleName.ScientificName @>`.
     let xpathOf selector (sample: BioSample) : string =
         XPathTracking.xpathOf selector sample
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (sample: BioSample) : string =
+        XPathTracking.xpointerOf selector sample

src/BioFSharp.IO.INSDC/Experiment.fs

@@ -22,8 +22,12 @@ module Experiment =
     let writeString (experiment: Experiment) : string =
         XmlSerializer.writeString experiment
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `experiment`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `experiment`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `experiment |> Experiment.xpathOf <@ fun e -> e.StudyRef.Accession @>`.
     let xpathOf selector (experiment: Experiment) : string =
         XPathTracking.xpathOf selector experiment
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (experiment: Experiment) : string =
+        XPathTracking.xpointerOf selector experiment

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

@@ -9,8 +9,9 @@ open System.Xml.Serialization
 
 open Microsoft.FSharp.Quotations
 
-/// Resolves the concrete, position-qualified W3C XPointer of a property on a parsed INSDC value.
-/// Public entity modules expose this as `<Entity>.xpathOf`. The property is named with a quotation
+/// 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
 /// (`<@ fun b -> b.Name @>`) rather than piped by value, because a scalar value carries no
 /// back-reference to its property, owner, or array position. The XPath is derived from the same
 /// `System.Xml.Serialization` attributes the serializer uses, with array positions taken from the
@@ -119,11 +120,15 @@ module XPathTracking =
                     current <- value
         sb.ToString()
 
-    /// Resolve the `#xpointer(...)` fragment selector for the property named by `selector` on the
-    /// parsed `root` value, with real array positions taken from the indices in the quotation.
+    /// The bare absolute XPath for the property named by `selector` on the parsed `root` value
+    /// (`/PROJECT/NAME`), with real array positions taken from the indices in the quotation.
     let xpathOf (selector: Expr<'Root -> 'P>) (root: 'Root) : string =
         let steps =
             match (selector :> Expr) with
             | Patterns.Lambda(_, body) -> parseChain body
             | _ -> failwith "Expected a selector lambda, e.g. <@ fun x -> x.Prop @>."
-        "#xpointer(" + build typeof<'Root> steps (box root) + ")"
+        build typeof<'Root> steps (box root)
+
+    /// 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 + ")"

src/BioFSharp.IO.INSDC/Receipt.fs

@@ -23,8 +23,12 @@ module Receipt =
     let writeString (receipt: Receipt) : string =
         XmlSerializer.writeString receipt
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `receipt`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `receipt`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `receipt |> Receipt.xpathOf <@ fun r -> r.Submission.Accession @>`.
     let xpathOf selector (receipt: Receipt) : string =
         XPathTracking.xpathOf selector receipt
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (receipt: Receipt) : string =
+        XPathTracking.xpointerOf selector receipt

src/BioFSharp.IO.INSDC/Run.fs

@@ -22,8 +22,12 @@ module Run =
     let writeString (run: Run) : string =
         XmlSerializer.writeString run
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `run`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `run`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `run |> Run.xpathOf <@ fun r -> r.ExperimentRef.Accession @>`.
     let xpathOf selector (run: Run) : string =
         XPathTracking.xpathOf selector run
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (run: Run) : string =
+        XPathTracking.xpointerOf selector run

src/BioFSharp.IO.INSDC/Study.fs

@@ -22,8 +22,12 @@ module Study =
     let writeString (study: Study) : string =
         XmlSerializer.writeString study
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `study`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `study`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `study |> Study.xpathOf <@ fun s -> s.Descriptor.StudyTitle @>`.
     let xpathOf selector (study: Study) : string =
         XPathTracking.xpathOf selector study
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (study: Study) : string =
+        XPathTracking.xpointerOf selector study

src/BioFSharp.IO.INSDC/Submission.fs

@@ -22,8 +22,12 @@ module Submission =
     let writeString (submission: Submission) : string =
         XmlSerializer.writeString submission
 
-    /// Resolve the position-qualified W3C XPointer fragment selector for a property of a parsed
-    /// `submission`. Name the property with a quotation, addressing array positions with `.[i]`:
+    /// Resolve the absolute XPath of a property of a parsed `submission`. Name the property with a
+    /// quotation, addressing array positions with `.[i]`:
     /// `submission |> Submission.xpathOf <@ fun s -> s.SubmissionLinks.[0].XrefLink.Db @>`.
     let xpathOf selector (submission: Submission) : string =
         XPathTracking.xpathOf selector submission
+
+    /// As `xpathOf`, but wrapped as a W3C XPointer fragment selector (`#xpointer(...)`).
+    let xpointerOf selector (submission: Submission) : string =
+        XPathTracking.xpointerOf selector submission