Bosak.XPath.Api 0.12.0-beta

<div align="center"> <img src="assets/logos/fytala-logo-color-dark.svg" width="100" alt="Fytala Bosak XPath engine"> <br><br> <h1>Bosak XPath</h1> <p>A high-performance, XDM-first XPath 3.1, XSLT 3.0 and XQuery 3.1 engine for .NET</p> </div>

<div align="center">

</div>

About FYTALA

FYTALA — Feeling Young, Thriving, Active, Learning Always — is a personal initiative founded after retirement, driven by the belief that curiosity, enthusiasm, and learning have no age limit.

It is about staying engaged, exploring new ideas, and sharing the excitement of technology and innovation with others. A special ambition of FYTALA is to spark that enthusiasm in young people and encourage them to discover how fascinating technology can be—not just by talking about technology, but by making it visible, tangible, surprising, and fun.

My dream captures that ambition perfectly: to walk into a classroom one day, side by side with a humanoid robot, and make my enthusiasm for technology and innovation contagious.

If that experience inspires even a few young minds to start asking questions, experimenting, building, programming, or imagining what might be possible, FYTALA has achieved something worthwhile.

Technology, after all, is not just about machines, electronics, or software. It is about curiosity, creativity, and turning ideas into reality. FYTALA therefore takes a deliberately broad perspective, embracing software, electronics, engineering, science, artificial intelligence, robotics, and whatever comes next.

Experimenting matters.

Making mistakes matters.

Understanding why something works matters even more.

Every project is an opportunity to learn something new and, hopefully, to help someone else learn as well.

The cable-stayed bridge in the FYTALA logo represents that philosophy. A bridge connects places, but it can also connect people, ideas, generations, and fields of knowledge. Its strength comes from many individual elements working together—much like technology itself.

FYTALA wants to help build those bridges: between experience and youthful curiosity, theory and practice, and imagination and real-world creation. It encourages looking beyond the obvious, asking questions, taking things apart, and building them again in new ways.

Above all, FYTALA is about keeping the desire to discover alive—and passing that desire on to the next generation.

Because we never have to stop being curious.

We never have to stop creating.

And we are never too old—or too young—to learn something new.

Overview

Bosak is a ground-up .NET implementation of XPath 3.1 (with forward-compatibility for 4.0), with full XSLT 3.0 and XQuery 3.1 processors built on the same expression engine.

The project is named for Jon Bosak, who chaired the W3C working groups that created XSLT and XPath and donated the XML logo to the community — the standards this engine implements.

Unlike System.Xml.XPath, Bosak is built on the W3C XQuery Data Model (XDM) from day one. Expressions are compiled once to an intermediate representation (IR) and executed many times on a lightweight, register-based virtual machine. XSLT and XQuery reuse the same XPath engine for all expression evaluation.

Key Features

• XDM-First Architecture — All inputs are adapted to IXdmNode; no proprietary DOM lock-in
• Compile Once, Execute Many — Parse → Optimize → Lower to IR → VM execution
• Zero-Allocation Sequences — Lazy struct enumerators avoid IEnumerable<T> boxing on hot paths
• Pluggable Backends — Works with XDocument, XmlDocument, streaming readers, or custom IXdmNode providers
• XPath 3.1 Complete — Maps, arrays, higher-order functions, arrow expressions (=>), string concat (||), FLWOR, JSON functions
• XSD Regex with Pinned Unicode 9.0 — Full \p{X}/\P{X} category and \p{IsBlock} support, class subtraction, astral-safe matching
• XSLT 3.0 Transform Engine — Template matching, sequence constructors, xsl:copy/xsl:copy-of, xsl:for-each-group, xsl:analyze-string, xsl:where-populated, xsl:on-empty, xsl:iterate/xsl:break, fn:transform()
• Burst-Mode Streaming Input — XmlStreamingProvider + XsltExecutable.TransformStreaming/TransformStreamingToString process multi-GB record documents in bounded memory (verified at 500k records); forward-only with loud errors instead of silent data loss; pre-root comment/PI parity with the in-memory provider; push-style streaming accumulators (xsl:accumulator works over the stream)
• XQuery 3.1 (Phase 4) — full core FLWOR, direct and computed constructors, switch/typeswitch, validate (strict/lax/type QName), output declarations and serialization, user-defined functions and variables, library modules (import module with %public/%private visibility), schema-aware user-defined simple types, QName/NOTATION preservation and ID/IDREF detection, higher-order function item instance-of over element kind tests, empty document-node() matching, constructed-element xs:anyType annotations, QName accessor singleton-sequence XPTY0004, function return-type atomization for user-defined schema types, keywords as unprefixed function names, instance-of type-hierarchy semantics for user-defined schema types; schema-aware fn:json-to-xml with validate:=true() against the W3C schema-for-JSON; QT3 wired (31,142/0/679 strict — 100% of runnable)

Quick Start

dotnet add package Bosak.XPath.Api --prerelease   # XPath entry point
# or: dotnet add package Bosak.Xslt --prerelease  # XSLT 3.0 transforms
# or: dotnet add package Bosak.XQuery --prerelease # XQuery 3.1 queries

using Bosak.XPath.Api;
using Bosak.XPath.Core.Xdm;

// Compile once
var expr = XPath31Expression.Compile("$price * (1 + $taxRate)");

// Execute many times with different inputs
var ctx = new EvaluationContext()
    .WithVariable("price", XdmValue.FromDecimal(100.00m))
    .WithVariable("taxRate", XdmValue.FromDecimal(0.21m));

var result = expr.Evaluate(ctx);
Console.WriteLine(result.DecimalValue); // 121.00

Conditional Expressions

var expr = XPath31Expression.Compile(
    "if ($score ge 90) then 'A' else if ($score ge 80) then 'B' else 'C'");

Sequence & Range

var expr = XPath31Expression.Compile("1 to 5");
// Returns: [1, 2, 3, 4, 5]

XQuery 3.1

using Bosak.XQuery.Api;
using Bosak.XPath.Core.Xdm;

var query = new XQueryCompiler().Compile("for $i in 1 to 3 return $i * $i");
var result = query.Evaluate(new XQueryContext());

foreach (var item in XdmSequence.FromSource(result.SequenceValue!))
    Console.WriteLine(item.IntegerValue);
// => 1 4 9

Architecture

flowchart TB
    subgraph Input["📄 Input"]
        XPATH["XPath 3.1 Expression"]
    end

    subgraph Compiler["🔧 Compiler Pipeline"]
        LEXER["Lexer<br/><small>ReadOnlySpan&lt;char&gt;</small>"]
        PARSER["Parser<br/><small>Recursive Descent AST</small>"]
        OPTIMIZER["Optimizer<br/><small>Constant Fold / DCE</small>"]
        LOWERER["IR Lowerer<br/><small>Register-Based IR</small>"]
    end

    subgraph Runtime["⚡ Runtime"]
        VM["Register VM<br/><small>VmEngine.Execute</small>"]
        FUNCS["Function Library<br/><small>fn, math, map, array, xs</small>"]
    end

    subgraph Output["📤 Output"]
        XDM["XdmValue"]
    end

    XPATH --> LEXER
    LEXER --> PARSER
    PARSER --> OPTIMIZER
    OPTIMIZER --> LOWERER
    LOWERER --> VM
    VM --> XDM
    FUNCS --> VM

    classDef current fill:#F0FFF0,stroke:#518D8F,color:#2F4F4F,stroke-width:2px
    classDef external fill:#FFFFFF,stroke:#293F5F,color:#2F4F4F

    class LEXER,PARSER,OPTIMIZER,LOWERER,VM,FUNCS current
    class XPATH,XDM external

Layer Stack

Performance Strategy

Roadmap

Support

The open-source library is community-supported and free forever (Apache-2.0):

• Questions & usage help → GitHub Discussions (Q&A category)
• Bugs & feature requests → GitHub Issues
• Engine correctness work — conformance fixes and correctness improvements are always done in the open; they are never paywalled

For guaranteed response times, direct engineering access, priority triage, or custom development, Fytala offers commercial support contracts. A future "Bosak Pro" add-on is planned for advanced schema-awareness scenarios; the conformant engine core stays Apache-2.0 regardless.

VS Code Extension

A Language Server Protocol (LSP) implementation and VS Code extension provide IDE features for XPath, XSLT, and XQuery development — syntax highlighting, semantic tokens, diagnostics, completion, hover, go-to-definition, document outline, code actions (quick fixes), code lens for .xpath/.xq/.xqy/.xquery results, XSLT Run XSLT transformation and Run initial template lenses, workspace/executeCommand evaluation, and evaluate/run commands.

Quick Install

# 1. Build the language server
dotnet build src/Bosak.LanguageServer/Bosak.LanguageServer.csproj

# 2. Build the extension
cd vscode-bosak
npm install
npm run compile

# 3. Open in VS Code and press F5 to launch the Extension Development Host

See vscode-bosak/README.md for full installation options (VSIX, custom server path, troubleshooting).

Building

dotnet build Bosak.sln
dotnet test Bosak.sln

Target framework: .NET 10.

All 2,111 unit tests pass (0 failures).

Conformance Testing

Bosak includes a W3C QT3 test suite harness for measuring XPath 3.1 standards compliance.

Running the Harness

# Build the conformance runner
dotnet build tests/Bosak.XPath.Conformance/Bosak.XPath.Conformance.csproj

# Run against the full QT3 suite (~32,000 tests across 428 test sets)
dotnet run --project tests/Bosak.XPath.Conformance/Bosak.XPath.Conformance.csproj

The harness:

1. Discovers all test sets from tests/qt3tests/catalog.xml
2. Filters out unsupported features (schema-aware, XSLT streaming-only, serialization, static typing)
3. Routes XQuery-syntax tests through the Bosak.XQuery pipeline; evaluates the rest via the public XPath31Expression.Compile(expr).Evaluate(ctx) API
4. Executes each test with environment-defined namespaces, variables, and context documents wired in
5. Compares results against QT3 assertions (assert-eq, assert-true, assert-xml, etc.) with strict error-code matching

Current Results

Strict error matching — Both conformance harnesses now require the declared <error code="..."> to match the raised exception; previously any error satisfied an error expectation. The XSLT strict count (2026-09-01) exposed 147 tests that passed with a wrong error code (lenient figure 7,627/103/6,870). The QT3 strict tightening (2026-09-07) exposed 1,200 wrong-code passes; the triage fixed ~970 of them — cast-matrix error codes, static XPST0003/XPST0081/XPST0008 checks at parse/compile time, XQDY0054 dynamic detection, FOER0000 structural matching — leaving 233 triaged failures (documented engine gaps: schema list-type casts, extreme date/time ranges, JSON parse error-code granularity). No genuinely passing test was lost in either sweep.

Known Limitations

Adding New Tests

The harness is intentionally thin — it validates the public API surface end-to-end rather than calling internal layers directly. This ensures that parser, compiler, VM, and standard-library fixes are all exercised together.

<div align="center" style="background:#2F4F4F; color:#F0FFF0; padding:1rem; border-radius:12px; margin-top:2rem;"> <p style="margin:0; font-family:Poppins,Segoe UI,sans-serif;"> <strong>© Fytala</strong> — Bosak XPath Engine </p> </div>