Formal evaluation semantics, SPARQL/XPath conformance, XSLT focus, Iterate

[namedgraph]

Summary

Turns formal-semantics.md from a type catalog into an actual semantics, and aligns the implementation and test suite with it. Follow-up to the architecture evaluation (architecture-evaluation.md, first commit).

• Formal definition (§3.8): abstract syntax, semantic domains (environment, focus, world), the big-step judgment ρ, φ ⊢ ⟨e, σ⟩ ⇓ ⟨v, ρ′, σ′⟩ with the full rule set, operator interpretation with effect classes, and metatheory (termination, determinism, ForEach-concurrency soundness). §3.8 is the definition; the §§3.2–3.7 prose restates it.
• Document model (§2): syntactic form discrimination (operation call / URI reference / RDF data / generic object / sequence / scalar), the {"@id": …} URI reference form, scalar coercion table, normative JSON-LD reserved-key list, base-IRI rule.
• Evaluation rules pinned: eager depth-first evaluation with declared quoted operands, sequence scoping (fresh variable scope per sequence and per ForEach iteration), error taxonomy, effect ordering. Resolves the bulk of tests/SPEC_GAPS.md (42 formerly UNCLEAR(spec) tests un-skipped).
• SPARQL 1.1 / XPath conformance — no divergences: Str, Concat, Replace, EncodeForURI, STRUUID now follow their W3C signatures exactly (simple literals materialized as plain rdflib literals, as rdflib's own SPARQL engine does). Replace gains the flags argument and XPath $N replacement syntax with err:FORX* conditions.
• XSLT focus: ForEach establishes (item, position, size); new Position and Last operations per fn:position()/fn:last(); Value's focus-item lookup closed to Binding + mapping.
• Iterate ported from REST-VKG (XSLT 3.0 xsl:iterate-inspired): params / quoted operation / quoted next-iteration / structured break, normative 1000-iteration cap (keeps the algebra terminating). The operation catalog is now a strict superset of the Java/XML implementation's.
• Linked Data response contract (§4.3–4.4): HTTP operations are RDF-specific and symmetric; conneg is transparent; non-RDF responses raise ValueError.
• Interpreter fixes: mutable default arguments across all operations (variable leakage between documents in one process), bool→xsd:integer coercion bug, Substitute's invalid _: N BNode serialization, Execute dropping the variable environment, scope-leaking list evaluation.

⚠️ Breaking changes

Deliberate, conformance-driven; a major version bump is warranted:

• Str: language tags are no longer preserved (STR("hallo"@de) → "hallo", per SPARQL); Str(BNode) now raises TypeError; results are simple literals (no datatype), not xsd:string.
• EncodeForURI, STRUUID: return simple literals instead of xsd:string (datatype-sensitive comparisons change).
• Concat: result kind now follows SPARQL CONCAT rules (was always xsd:string); shared language tags are carried.
• Replace: replacement syntax is now XPath ($1 for groups; bare $/\ are errors — previously literal); zero-length-matching patterns and invalid flags now raise ValueError; language-tagged pattern/replacement now TypeError; result kind follows the first argument.
• URI(BNode) and Substitute with a BNode binding: now TypeError (previously returned garbage).
• Value: attribute lookup on arbitrary objects removed — focus-item shapes are closed to Binding + mapping (ValueError otherwise).
• Current (and context-Value) outside ForEach: now ValueError (previously returned the default empty context).
• Variable scoping: sequences and ForEach iterations now push/pop scopes — bindings no longer leak across iterations or out of nested sequences (previously leaked when an outer scope existed).
• Scalar coercion: JSON booleans now coerce to xsd:boolean (previously xsd:integer via a bool-before-int bug); null is now a TypeError (previously the literal "None").
• {"@id": "..."} objects: an object whose only member is @id now evaluates to a URI (the new URI reference form) instead of passing through as JSON-LD data.
• ForEach context: operations now receive a Focus object rather than the bare item — third-party Operation subclasses that read self.context directly must unwrap it (all in-tree operations updated).
• Filter: non-integer expressions raise TypeError (was NotImplementedError).
• HTTP/SPARQL responses: non-RDF or unparseable responses raise ValueError (previously AttributeError/raw rdflib parser errors leaked).

Test plan

• uv run pytest: 260 passed, 8 skipped (live-service/LLM-dependent), 20 deselected (network/sparql/ldh markers) — up from 145/50 on main.
• uv run ruff check src tests: clean.
• New suites: document model & scoping, client response contract (stub opener, offline), Position/Last, Iterate (incl. the 1000-cap and cursor threading), Concat.

🤖 Generated with Claude Code