Source Map & Module Directory

Complete walkthrough of the repository layout. Every path is relative to the repo root. Symbols are cited by name with links — JSR doc page for root exports, GitHub blob for deep imports — and no line numbers, per this wiki’s detail_level: minimal (see 08 — Wiki Maintenance).

sparql-engine/
├── deno.json                 package manifest (JSR), tasks, imports (@/ → ./src/)
├── README.md                 usage + parity + benchmarking overview
├── ARCHITECTURE.md           topology, contracts, @worlds/sdk relationship
├── CONTEXT.md                glossary (engine, parity, spec-wins divergence, ...)
├── src/                      the package (all engine code)
│   ├── mod.ts                public exports (the root entrypoint)
│   ├── sparql-engine-interface.ts   request/response envelopes
│   ├── wazoo-sparql-engine.ts       engine orchestrator
│   ├── quad-store.ts                store adapters + quad indexes
│   ├── parser/                     vendored SPARQL parser
│   ├── planner/                    join-cost estimator + join-order search
│   ├── evaluator/                  query & update evaluation
│   ├── store/                      rdfjs.Store implementations
│   ├── serialize/                  results serializers (.srj/.srx) + Turtle writer
│   └── term/                       term algebra (identity/convert/order/...)
├── test/
│   ├── parity/               differential tests vs Comunica
│   └── w3c/                  W3C SPARQL 1.1/1.2 + RDF 1.1/1.2 gates, fixtures/
├── cli/                      `sparql` command (deno compile entry + runtime-agnostic core)
├── bench/                    benchmarks + regression budget
├── docs/                     this wiki
├── playground/               browser SPARQL playground (static page + bundle)
└── .github/workflows/        ci.yml (ci, w3c-parity, latency-snapshot,
                              docs-drift, docs-links jobs), pages.yml
                              (GitHub Pages deploy), publish.yml

src/ — the package

Entry point

File Symbols Role
src/mod.ts re-exports everything public The full-engine entrypoint (exports["."] in deno.json), incl. SparqlSyntaxError and the planner/estimator surface. deno.json also exposes subpath entrypoints: ./term → src/term/mod.ts, ./store → src/store/memory-store.ts, ./parser → src/parser/mod.ts, ./serialize → src/serialize/mod.ts, ./data-model → src/term/mod.ts (alias of ./term). Anything not re-exported through one of these is private surface.

Engine core

File Symbols Role
src/sparql-engine-interface.ts SparqlEngineInterface, SparqlRequest, SparqlResponse, SparqlAskResults, SparqlSelectResults, SparqlConstructResults, SparqlValue, SparqlBinding Typed envelopes (single source of truth; @worlds/sdk re-exports them from @wazoo/sparql-engine).
src/wazoo-sparql-engine.ts WazooSparqlTransaction, WazooSparqlEngineOptions, WazooSparqlEngine, IriFunction, IriFunctionMap Orchestrator: parse → dispatch query/update. Implements SparqlEngineInterface; the engine @worlds/sdk’s durable clients wire in.
src/quad-store.ts QuadIndex, buildQuadIndex, probeQuadIndex, storeVersion, matchQuads, simplePredicate, GraphScopedStore, namedGraphs, buildDatasetStore The store-adapter layer: positional indexes, graph scoping, active-dataset materialization; stream draining and store statistics delegate to boundary modules.
src/quad-store-stream.ts matchQuadsViaStream Drains a generic RDF/JS store.match stream into an array; native builds map this module to a stub, so matchQuads resolves scans through MemoryStore only.
src/quad-store.test.ts — Unit tests for the adapter layer.
src/wazoo-sparql-engine.test.ts — engine integration suite (concurrency, EXISTS snapshot isolation, baseIri, custom functions, planner order).

src/parser/ — vendored SPARQL parser

File Symbols Role
src/parser/sparql-parser.ts SparqlParser The engine’s parser entry: wraps Parser with sparqlStar: true and the standard xsd: prefix.
src/parser/mod.ts SparqlParserOptions, Parser (aliased SparqlParser) Maintained wrapper over the generated parser; injects the zero-dep DataFactory, sets base/prefixes per parse. Re-exports SparqlSyntaxError.
src/parser/ast.ts Term … SparqlQuery (every AST type) sparqljs-compatible AST shape, incl. ReifiedQuad (, tripleTerm/reifier markers) and PropertyPath.
src/parser/parser.ts generated Pure-ESM jison parser generated from sparql.jison; never hand-edited.
src/parser/syntax-error.ts SparqlSyntaxErrorKind, SparqlSyntaxErrorDetails, SparqlSyntaxError, toSparqlSyntaxError Line/column-positioned parse errors surfaced as SparqlSyntaxError (issue #121); exported from the root entrypoint.
src/parser/sparql.jison — Grammar source of truth: sparqljs 3.7.4 + SPARQL 1.2 patches (direction functions, triple terms, reifiers, annotations).
src/parser/generate-parser.ts — Codegen script (deno task parser:generate); --check verifies sync.
src/parser/turtle-parser.ts parseTurtleQuads Turtle/TriG/N-Triples/N-Quads parser (typed, generated from a jison grammar) backing LOAD; RDF 1.2 triple terms/reifiers included.
src/parser/turtle-generated.ts generated Generated from src/parser/turtle.jison.
src/parser/lr-runtime.ts LrParser, LrLexer Typed LR driver and lexer loop extended by the generated Turtle parser; rules match as sticky patterns at the current offset, so tokenizing stays linear in document size.
src/parser/turtle-context.ts turtleContext Typed parse context and semantic actions for the Turtle grammar.
src/parser/sparql-context.ts sparqlContext Typed parse context and semantic actions for the Turtle grammar.
src/parser/term-values.ts namedNodeTerm, literalTerm, quadTerm Typed parse context and semantic actions for the Turtle grammar.
src/parser/rdf-terms.ts RdfTerm Typed parse context and semantic actions for the Turtle grammar.
src/parser/turtle.jison — Grammar for the Turtle/TriG/N-Triples/N-Quads superset parser (RDF 1.2 triple terms/reifiers).
src/parser/README.md — Parser architecture, the exact SPARQL 1.2 patch, regeneration procedure.
src/parser/mod.test.ts, turtle-parser.test.ts — Parser unit tests.
src/parser/LICENSE — Upstream sparqljs MIT license (required for redistribution).

src/evaluator/ — evaluation

File Symbols Role
sparql-evaluator.ts SparqlEvaluatorOptions, SparqlEvaluator Query dispatch (SELECT/ASK/CONSTRUCT/DESCRIBE), FROM-dataset setup, CONSTRUCT/DESCRIBE assembly, ORDER BY.
bgp-evaluator.ts ExistsSnapshot (internal), BgpEvaluatorOptions, BgpEvaluator, patternListContainsExists Pattern algebra: group evaluation, OPTIONAL/MINUS/UNION/GRAPH/BIND/VALUES, subqueries, and the synchronous EXISTS evaluator (per-call snapshot, issue #72).
join.ts TermBinding, ScanEntry, BindingFilter, bindingsCompatible, leftJoin, innerJoin, minus, filterBindings, mapBindings, scanEntry, joinTriplePattern, joinTriplePatternLazy, PathPair, PathEntry, PathElement, isPropertyPath, isMultisetPath, scanPathEntry, joinPathPattern, joinPathPatternLazy, matchQuadsSync, graphNodesSync, pathStepsSync, scanPathEntrySync The join engine: hash joins, binding-set algebra, property paths, lazy generator joins, plus the synchronous twins used by EXISTS.
expression-evaluator.ts ExpressionEvaluationContext, IriFunction, IriFunctionMap, ExpressionEvaluatorOptions, ExpressionEvaluator SPARQL expression evaluation: operators, string/numeric/date functions, XSD constructors, hashes, EXISTS hooks.
expression-utils.ts expressionContainsExists, expressionContainsAggregate AST walks that decide whether the EXISTS index / aggregate path is needed.
select-pipeline.ts SelectSolution, pipelineNeedsExistsIndex, applySelectPipeline The shared SELECT post-processing pipeline (VALUES, grouping, HAVING, ORDER BY, projection, DISTINCT/REDUCED, OFFSET/LIMIT).
aggregate.ts SolutionGroup, groupSolutions, aggregateValue GROUP BY partitioning and aggregate computation (exact BigInt sums).
abort.ts checkAborted Cooperative cancellation: the evaluator throws at the next pattern/join boundary when the request’s signal fires or timeoutMs elapses.
reified.ts RDF_REIFIES, expandReifiedTriples, isReifiesPattern RDF 1.2 reified-triple pattern expansion into rdf:reifies triples.
update-evaluator.ts QuadWriteStore, UpdateEvaluatorOptions, UpdateEvaluator SPARQL Update execution: all operation types, transactions, template instantiation, DELETE matching, LOAD.
update-evaluator.test.ts — Update unit tests.
join.test.ts — Join-engine unit tests (hash joins, property paths, sync twins).

src/store/ — RDF/JS stores

File Symbols Role
memory-store.ts Listener, MemoryStream, MemoryStore Zero-dependency in-memory store; re-exports the RDF/JS stream.
memory-store.test.ts — Store unit tests.
quad-stream.ts MemoryStream, subscribeQuadData, matchQuadStream Deno-only RDF/JS stream surface; native builds map it to a stub.
store-statistics.ts estimateStatsViaStore Optional store statistics hook lookup; native builds map it to a fallback stub.

The durable node:sqlite store (SqliteStore) moved to @worlds/sqlite on 2026-08-17 — its source, unit tests, and crash-recovery suite live at src/sqlite/rdfjs-store/ in that repo.

src/planner/ — join ordering

File Symbols Role
join-cost-estimator.ts JoinCostEstimator, BaselineJoinCostEstimator The injectable cost model behind the greedy reorderer; default is the baseline formula (WazooSparqlEngineOptions.estimator).
pattern-statistics.ts PatternStats, StoreStatisticsHook, DISTINCT_SAMPLE_CAP, patternSignature, PatternStatistics, fallbackStats Per-query statistics source: store estimateStats hook, scoped candidate fallback, bounded distinct-value pass (issue #129).
pattern-statistics-hook.ts createPatternStatisticsHook Binds a store’s optional estimateStats hook; native builds map it to a stub that always reports no hook.
join-order-search.ts DP_MAX_PATTERNS, EstimatedJoinState, boundVariables, estimatedJoinCost, searchBestJoinOrder Subset DP over the 2^n join orders for small BGPs (≤ DP_MAX_PATTERNS, issue #130), greedy fallback for larger/custom-estimator cases.
*.test.ts (×3) — Planner unit tests (estimator formula, DP optimality, statistics derivation).

src/serialize/ — serializers

File Symbols Role
mod.ts re-exports the writers (JSON, XML, Turtle) The ./serialize subpath entrypoint (exports["./serialize"] in deno.json).
json-results.ts serializeJsonResults SPARQL results JSON (.srj) writer over the wire value shapes.
xml-results.ts serializeXmlResults SPARQL results XML (.srx) writer; the writers only import types from the engine.
turtle-writer.ts serializeTurtle, TurtleFormat, TurtleWriterOptions Zero-dependency Turtle/N-Quads/N-Triples writer; turtle emits TriG graph blocks for named graphs.
json-results.test.ts / xml-results.test.ts / turtle-writer.test.ts — Round-trip writer tests.

src/term/ — term algebra

File Symbols Role
mod.ts re-exports the term layer Single import point for the evaluator.
identity.ts termKey, sameRdfTerm Sound identity: hashing keys and structural equality.
convert.ts sparqlTermToRdfTerm, rdfTermToSparqlValue AST ⇄ RDF/JS ⇄ wire conversion.
canonical.ts CanonicalTerm, canonicalizeRdfTerm, canonicalizeSparqlValue Serialization-stable projections for differential parity.
numeric.ts XSD*, NUMERIC_DATATYPES, numericValue, compareNumericValues, formatNumber, canonicalDouble Numeric value semantics + canonical double lexical form.
ordering.ts compareRdfTerms SPARQL §12.4 term ordering for ORDER BY / MIN / MAX / DISTINCT.
datetime.ts DateTimeParts, parseDateTime, timezoneDurationLexical xsd:dateTime parsing and timezone handling.
hash.ts md5Hex, sha1Hex, sha256Hex, sha384Hex, sha512Hex Zero-dependency hash implementations for the hash functions.
data-factory.ts NamedNodeImpl … DataFactory, dataFactory Zero-dependency RDF/JS factory (also used by the parser).
term.test.ts — Term unit tests.

test/ — verification surface

Path Role
test/parity/parity.test.ts Differential query parity vs @comunica/query-sparql-rdfjs-lite
test/parity/parity-update.test.ts Differential update parity (final store contents, up to bnode relabeling)
test/parity/parity-harness.ts Shared harness: canonicalization, blank-node normalization, Comunica engine setup
test/parity/parity-fixtures.ts Seeded stores for parity cases
test/parity/canonical-store.test.ts Unit-tests canonicalStoreQuads blank-node substitution (repeated placeholders, isomorphism)
test/w3c/w3c-main.ts SPARQL 1.1 evaluation-core differential runner (deno task test:w3c)
test/w3c/sparql12-main.ts, sparql12-gap.ts SPARQL 1.2 suite + RDF 1.2 triple-terms gap suite
test/w3c/rdf-differential.ts, rdf-classify.ts RDF 1.1/1.2 Turtle/TriG/N-Triples/N-Quads gates
test/w3c/ref-crosscheck.ts Allowlisted-divergence audit vs Oxigraph + N3.js
test/w3c/exists-ref.ts EXISTS subquery surface vs Oxigraph
test/w3c/runner.ts, manifest.ts, divergences.ts, rdf-harness.ts W3C harness plumbing, manifest parsing, documented divergences, CONSTRUCT multiset contract (issue #87)
test/w3c/construct-semantics.test.ts Pins the CONSTRUCT graph-result contract: reference deduplicated, wazoo as-emitted, duplicates fail
test/w3c/fixtures/ Vendored W3C suites: sparql11/, sparql12/, rdf/ (offline, deterministic)
test/publish-graph-check.ts Fails if the default export graph gains node:/npm: runtime imports (deno task publish:check)

bench/

File Role
bench/engine_bench.ts Three-engine benchmark (wazoo / Comunica / Oxigraph) with verification-first equality asserts
bench/budget.ts Regression budget gate (deno task bench:check): avg ms/iter against bench/baseline.json
bench/baseline.json maxAllowedMs: 50, maxRegressionRatio: 0.15
bench/concurrency-probe.ts EXISTS concurrency stress probe (issue #72): shuffled Promise.all rounds + update interleaving, exit 1 on error/mismatch
bench/measure-libs.ts On-disk footprint of wazoo JSR artifact vs Oxigraph npm vs Comunica transitive closure → bench/size-data.json
bench/measure-closures.ts Per-entrypoint value-import closure (. + ./term/./data-model/./store/./parser/./serialize) → bench/closures-data.json
bench/collect-memory.ts Spawns bench/memory-probe.ts per engine × workload, merges peak-heap results → bench/memory-data.json
bench/memory-probe.ts Peak heapUsed per engine (wazoo/Comunica/Oxigraph) on full-scan + nested-EXISTS workloads over a 10k-person graph
bench/size-data.json, memory-data.json, closures-data.json Measured snapshots consumed by bench/treemap.ts and the root README.md (Size & memory footprint)
bench/latency-chart.ts Renders bench/latency-data.json → docs/assets/chart-latency.svg (per-query-class bars)
bench/latency-check.ts CI gate: fresh deno bench --json inventory must match the committed snapshot (timings never compared)
bench/latency-data.json Committed latency snapshot (avg ms/iter per query class)
bench/cli-bench.ts Process-level sparql CLI bench (deno task bench:cli): binary size, cold start, isolated load stages, evaluation, and peak RSS. Target order rotates each round, stage times subtract inside a round, and the multiplier is the median of per-round ratios; any build honoring cli/run-cli.ts can be added as a --target
bench/cli-targets-bench.ts Deno.bench comparison of the CLI builds (deno task bench:cli:targets): deno run vs deno-compile vs scriptc, with deno-compile as the baseline
bench/cli-workloads.ts Shared CLI bench fixture (buildPeopleTurtle) and invocation table (startup/load/join) used by both CLI benches
bench/treemap.ts Renders bench/{size,memory,closures}-data.json into the
docs/assets/*.svg charts  

cli/ — the sparql command

File Role
cli/run-cli.ts Runtime-agnostic core: argument parsing, loading RDF files into a MemoryStore, one query, serialization
cli/deno-main.ts Deno host entrypoint compiled by deno task compile into dist/sparql
cli/run-cli.test.ts CLI contract tests: an in-memory host, plus every built host found in dist/ (skipped when absent)
cli/node-main.ts Node-API host entrypoint for scriptc native builds (issue #221)
cli/tsconfig.json scriptc compiler config: strict mode, @/ → ../src/ path mapping
cli/native-coverage.ts deno task native:coverage: pinned scriptc coverage of cli/node-main.ts, blockers by file and code
cli/native-build.ts deno task native:build: scriptc build of cli/node-main.ts into dist/sparql-node
cli/native-gate.ts deno task native:gate: coverage, build, then the cross-host CLI contract

cli/tsconfig.json maps four Deno-only modules to .native.ts stubs so the native module graph stays statically typed: src/store/quad-stream.ts and src/quad-store-stream.ts (RDF/JS stream construction and draining), plus src/store/store-statistics.ts and src/planner/pattern-statistics-hook.ts (optional store statistics hooks). The stubs throw or return the documented fallback; a native build constructs no quad stream and probes no store for statistics, answering scans through MemoryStore.getQuads instead.

docs/ — this wiki ↔ source mapping

Wiki page Primary sources it documents
docs/README.md Index + Pages setup
docs/01-quickstart.md src/mod.ts, deno.json tasks, README.md
docs/02-architecture.md src/wazoo-sparql-engine.ts, src/parser/, src/evaluator/, src/quad-store.ts
docs/03-api-contracts.md src/sparql-engine-interface.ts, src/wazoo-sparql-engine.ts, src/term/
docs/04-source-map.md this page — the whole tree
docs/05-testing.md test/parity/, test/w3c/, bench/, .github/workflows/ci.yml
docs/06-supplemental-context.md test/w3c/fixtures/, CONTEXT.md, ARCHITECTURE.md
docs/08-maintenance.md the whole tree — the Git-anchored sync procedure (deno doc --json symbol checks, git ls-tree inventory)
docs/durable-transactions.md @worlds/sqlite’s SqliteStore (pointer; full doc lives in the worlds-sqlite repo)

Where to change what