Release: IR pipeline, SPARQL conversion layer, and agent workflow

[flyon]

Summary

This PR brings dev into main with three major feature areas developed across multiple PRs:

1. Canonical Intermediate Representation (IR) pipeline

Replaced query internals with a backend-agnostic IR AST. All DSL queries now compile through a three-stage pipeline (desugar → canonicalize → lower) into canonical IR objects that any store can consume.

• getCanonicalIR() exposed on select factories
• Canonical mutation IR for create/update/delete
• IR documentation and golden test coverage

2. SPARQL conversion layer with SparqlStore base class

Full SPARQL pipeline: IR → SPARQL algebra → SPARQL string → execute → map results back to typed DSL objects.

New exports from @_linked/core/sparql:

• SparqlStore — abstract base class for SPARQL-backed stores. Extend it and implement two methods:

  import {SparqlStore} from '@_linked/core/sparql';
  
  class MyStore extends SparqlStore {
    protected async executeSparqlSelect(sparql: string): Promise<SparqlJsonResults> { /* ... */ }
    protected async executeSparqlUpdate(sparql: string): Promise<void> { /* ... */ }
  }

• IR → SPARQL string (full pipeline in one call): selectToSparql, createToSparql, updateToSparql, deleteToSparql

• IR → SPARQL algebra (for stores that want to inspect/optimize before serialization): selectToAlgebra, createToAlgebra, updateToAlgebra, deleteToAlgebra

• Algebra → string serialization: selectPlanToSparql, insertDataPlanToSparql, deleteInsertPlanToSparql, deleteWherePlanToSparql, plus serializeAlgebraNode, serializeExpression, serializeTerm

• Result mapping: mapSparqlSelectResult, mapSparqlCreateResult, mapSparqlUpdateResult — handles flat/nested/aggregated results with XSD type coercion

• All algebra types re-exported: SparqlTerm, SparqlTriple, SparqlAlgebraNode, SparqlExpression, SparqlSelectPlan, SparqlPlan, SparqlOptions, etc.

Key design decisions:

• SPARQL algebra aligned with SPARQL 1.1 spec §18 — inspectable/optimizable data structure before serialization
• Property triples wrapped in OPTIONAL (LeftJoin) so missing values produce nulls, not row elimination
• VariableRegistry with collision detection for SPARQL variable management
• NestingDescriptor tree for reconstructing nested result objects from flat SPARQL bindings
• XSD/RDF constants imported from ontology modules (no hardcoded URIs)

Bug fix: isNodeReference() in MutationQuery.ts — nested creates with predefined IDs now correctly insert entity data.

3. Agent workflow skills

Structured mode-based workflow for agent-assisted development: ideation → plan → tasks → implementation → review → wrapup.

Documentation

• SPARQL Algebra Layer — full type reference, conversion rules, store implementation guide
• Intermediate Representation — updated with SparqlStore reference
• README — pipeline walkthrough, type inference highlight, SparqlStore section
• Ideation docs for future work: named graphs, computed expressions, advanced query patterns

Test coverage

• ~200 unit tests: algebra, serialization, result mapping, golden SPARQL comparison, negative/edge cases
• 80 Fuseki integration tests: all query types end-to-end through SparqlStore (requires Docker)
• All existing tests pass (394 total non-Fuseki)

Changesets

• major: first major release
• minor: canonical IR pipeline
• minor: selectAll(), property shape deduplication, override guards
• minor: SPARQL conversion layer (SparqlStore, all conversion/mapping functions, algebra types)

Test plan

• npx tsc --noEmit passes
• All unit tests pass (394 passing)
• All Fuseki integration tests pass (80/80, requires Docker)
• Documentation reviewed and consistent with implementation

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	ulid@​3.0.2

View full report