Formal evaluation semantics aligned with REST-VKG: flat sequences, XSLT focus, SPARQL/XPath conformance

[namedgraph]

Summary

Turns formal-semantics.md from a type catalog into an actual semantics, aligns it with the Java/XML implementation in REST-VKG, and brings the Python implementation and test suite up to it. The evaluation model is stated as XSLT/XPath applied to RDF, with SPARQL contributing the data model and the term-level function library.

Spec

• Formal definition (§3.8): abstract syntax, semantic domains (environment, focus, world), the big-step judgment ρ, φ ⊢ ⟨e, σ⟩ ⇓ ⟨v, ρ′, σ′⟩ with the full rule set, operator effect classes, and metatheory (termination, determinism, when concurrent ForEach iterations are equivalent to sequential ones). §§3.2–3.7 restate it in prose.
• Document model (§2): syntactic form discrimination, the {"@id": …} URI reference form, scalar coercion, the closed JSON-LD reserved-key list, the base-IRI rule.
• Flat sequences (XDM): Unit is the empty sequence; the sequence form, ForEach and Iterate yield the concatenation of their values; a Result is one item.
• Effects (§3.6): iterations of a ForEach are unordered. Two iterations updating the same URI are an error, the algebra's XTDE1490, compared on the URI the write reports and counted through nested ForEaches. A read of what another iteration writes is implementation-dependent (XTRE1500).
• SPARQL 1.1 / XPath conformance, no divergences: Str, Concat, Replace (with flags and XPath $N), EncodeForURI and STRUUID follow their W3C signatures exactly.
• XSLT focus: ForEach establishes (item, position, size); Position and Last per fn:position()/fn:last().
• Iterate (xsl:iterate): params, quoted operation/next-iteration, structured break, normative 1000-iteration cap.
• Filter: by position from a sequence or result ($seq[2]), or by name from a row ($row?url).
• SPARQL operations (§4.3): SELECT/CONSTRUCT/DESCRIBE take exactly one of endpoint and graph; the graph case is pure. SPARQLString takes endpoint, question, projection (the as of xsl:evaluate) and context (explorations shown to the model), with bounded repair.
• Linked Data operations (§4.4): RDF-only and symmetric, with transparent conneg. A write returns (status, url), where url is the response's Location, otherwise the effective request URI. A write answered outside 2xx is an error. If-Match from a HEAD is transport, and the spec says what it does and does not protect against.
• Schema operations (§4.6): an optional bindings scope (?subject → VALUES); default and named graphs are read.
• §5: what each serialization still owes the spec. Appendix A: the extension-family table (XML waldh: ↔ JSON ldh-; JSON keeps the prefix because its names are also MCP tool names) and ldh-AddConstruct.
• Execute is removed; the document envelope is removed.

Implementation

• The interpreter follows §3.8: flat concatenation; scopes per sequence and per iteration; no mutable default arguments; the URI reference form.
• ForEach gate for the same-target rule (SameTargetError); Filter by name; SELECT/CONSTRUCT/DESCRIBE over a graph via rdflib.
• Writes: If-Match from HEAD; Location-aware url; WriteRefusedError (a ValueError) outside 2xx.
• SPARQLString ported from REST-VKG: projection and parse repair, context excerpts, an ASK check (for SELECT queries), AGENTS.md.
• Extraction queries are REST-VKG's, scoped by bindings, with a fallback for endpoints that refuse GRAPH.
• Iterate, Position, Last and ldh-AddConstruct added. The ldh-* string checks accept simple literals (RDF 1.1).
• Code health: an exception taxonomy (WebAlgebraError subclasses that also inherit the §3.7 built-ins) and an HTTP-client mixin.
• prompts/system.md and the README follow the catalog.
• Also included, though not used by the algebra: groundwork for an HTTP service, which sits in the same files. That is OperationKind (read/write/destructive) on operations, and an optional write recorder and CA bundle on the clients.

⚠️ Breaking changes

Deliberate and conformance-driven; hence 2.0.0.

• Sequences are flat: a JSON array, ForEach and Iterate concatenate their values. A ForEach/Iterate with an array body yields all its values, not the last one.
• ForEach: two iterations writing the same URI raise ValueError.
• Writes: a non-2xx answer raises ValueError (WriteRefusedError), not urllib.error.HTTPError. url is the Location when the server sends one. Writes to existing resources are now conditional (If-Match).
• SPARQLString: endpoint is required. The result is a simple literal; it is checked and may be regenerated.
• Execute is removed (unknown operation → ValueError).
• Str: language tags are no longer preserved; Str(BNode) raises TypeError; the result is a simple literal.
• EncodeForURI, STRUUID: return simple literals.
• Concat: the result kind follows SPARQL CONCAT rules.
• Replace: XPath replacement syntax ($1; bare $/\ are errors). Zero-length-matching patterns and invalid flags raise ValueError; language-tagged pattern/replacement raise TypeError.
• URI(BNode), Substitute with a BNode binding: TypeError.
• Value: focus-item lookup is closed to Binding + mapping. Current/Value outside ForEach: ValueError.
• Scalar coercion: booleans → xsd:boolean; null → TypeError.
• {"@id": "..."}: an object whose only member is @id is a URI.
• ForEach context: operations receive a Focus, not the bare item.
• Filter: a string expression is a name lookup on a row; other non-integer expressions raise TypeError.
• HTTP/SPARQL responses: a non-RDF or unparseable response raises ValueError.

Test plan

• pytest tests/unit: 443 passed, 8 skipped (live-service or LLM-dependent). Network/sparql/ldh markers are deselected. The tests are derived from the spec alone; HTTP is stubbed at the urllib boundary (tests/http_stub.py).
• ruff check src tests: clean.
• New suites: document model and scoping, write contract (Location, If-Match, refused writes), same-target rule, graph-queried SPARQL, extraction bindings, Filter by name, Position/Last, Iterate, Concat, ldh-AddConstruct.
• Open spec questions are tracked in tests/SPEC_GAPS.md. One example: what a relative IRI does inside a graph data form.

🤖 Generated with Claude Code