<../up/o> .', 'turtle', { baseIri: 'http://ex/dir/' });
// -> http://ex/dir/a ; <../up/o> -> http://ex/up/o
```
**Mutate in place (O(batch), no index rebuild).**
```js
store.update('PREFIX ex: INSERT DATA { ex:carol ex:name "Carol" }');
store.addQuads([DF.quad(DF.namedNode('http://ex/d'), DF.namedNode('http://ex/p'), DF.literal('o'))]);
store.removeQuads(store.match(null, DF.namedNode('http://ex/p')));
store.applyDelta(insertQuads, deleteQuads); // deletes applied first, then inserts
```
**Named graphs (load as a dataset).** Without `dataset: true`, all quads fold into the default graph and `GRAPH`/named-graph lookups see nothing. Applies to N-Quads, TriG, and a JSON-LD `@graph` (with an outer `@id`). `'jsonld'` parsing is compiled in only when the bundle is built with the opt-in `jsonld` feature (the published `@jeswr/sparq` bundle enables it — see the bundle-features note below); the lean default bundle omits it.
```js
const ds = await SparqStore.fromString(nquads, 'nquads', { dataset: true });
const namedBindings = await ds.queryBindings('SELECT ?g ?s WHERE { GRAPH ?g { ?s ?p ?o } }');
await new Promise((resolve, reject) => {
namedBindings.on('error', reject);
namedBindings.on('end', resolve);
namedBindings.on('data', (row) => {
console.log(row.get('g').value, row.get('s').value);
});
});
ds.update('INSERT DATA { GRAPH { "o" } }');
ds.match(null, null, null, DF.namedNode('http://ex/g')); // graph-aware
```
**Compressed ingest + memory-tight index.** `fromCompressed` sniffs the codec by magic number (`.nt.zst`, `.ttl.gz`); `{ compressed: true }` halves index memory at a small per-scan decode cost.
```js
const fromZst = await SparqStore.fromCompressed(zstBytes, 'ntriples'); // codec auto-sniffed
const compact = await SparqStore.fromString(bigTurtle, 'turtle', { compressed: true });
```
**CONSTRUCT / DESCRIBE.** `SparqStore.queryQuads(sparql)` returns the constructed/described graph as RDF/JS `Quad`s in the default graph (template bnodes freshened per solution; illegal slots dropped per §16.2). `queryQuadsString(sparql)` gives the raw N-Triples (a valid Turtle subset) and `queryQuadsStream(sparql, batchSize?)` streams the quads for a large graph. A SELECT/ASK routed here throws.
```js
const quads = store.queryQuads('PREFIX ex: CONSTRUCT { ?s ex:label ?n } WHERE { ?s ex:name ?n }');
quads[0].subject.value; // 'http://ex/alice'
for (const q of store.queryQuadsStream('DESCRIBE ')) { /* one Quad at a time */ }
const nt = store.queryQuadsString('DESCRIBE '); // raw N-Triples string
```
The raw `Store.queryQuads` / `queryQuadsChunks` (returning N-Triples strings) remain available for zero term-materialisation.
**Serialise / dump the store ([OPUS-4.8] sq-u78ol / #1117 / #1129, serialize-rdf bundle only).** The high-level **`SparqStore.serialize(format?, opts?)`** (with a `dump(format?, opts?)` alias) is the primary entry point — an options-object wrapper over the raw `Store.serialize(...)` below (`opts: { pretty?, indent?, abbreviate?, prefixes? }`, all defaulted: pretty Turtle, two-space indent, abbreviated, engine default prefixes). It throws a clear "requires a serialize-rdf-enabled wasm bundle" error on a lean bundle (rather than a cryptic "not a function").
```js
const ttl = store.serialize('turtle'); // pretty Turtle, default opts
const trig = store.dump('trig'); // dump() == serialize()
const mine = store.serialize('turtle', { prefixes: [['ex', 'http://ex/']] }); // caller prefix policy (#1129)
const full = store.serialize('turtle', { abbreviate: false }); // full <…> IRIs, no @prefix header
```
The raw wasm `Store.serialize(format, pretty, indent, abbreviate, prefixes?)` (positional) is the same engine writer. Where `queryQuads` writes a CONSTRUCT/DESCRIBE *result graph* as flat N-Triples, `serialize(...)` writes the **store itself** as a readable Turtle (default graph), TriG (whole dataset, named graphs as `GRAPH { … }` blocks), or JSON-LD (whole dataset) **string**. `pretty=true` indents the output (Turtle/TriG: the sorted, blank-line-separated `prettyTurtle` shape; JSON-LD: a structurally re-indented document); `indent` is the indent unit (`null`/`undefined` ⇒ two spaces, ignored when `pretty=false`). For Turtle/TriG, `abbreviate=true` emits a sorted `@prefix` header and compacts IRIs to `prefix:local`, `false` keeps full `<…>` IRIs. `prefixes` is an OPTIONAL `[[prefix, iri], …]` array selecting the compaction prefix map: omit it (`undefined`/`null`) for the engine's well-known defaults (`rdf`/`rdfs`/`xsd`/`owl`/`schema` → `http://schema.org/`/`foaf`/`dc`/`skos`/`sh`) — **byte-for-byte the prior behaviour** — or pass your OWN policy (the [`COMMON_PREFIXES`](../../packages/sparq-client/src/sparql-prefixes.ts) registry with `https://schema.org/` + `dcterms`/`prov`/`geo`/`void`/`ex` → `http://example.org/`, or a query's `declaredPrefixBindings(...)`) to drive `@prefix`/`@context` compaction under that policy and get byte-parity output. It applies to Turtle/TriG (with `abbreviate=true`) and the JSON-LD `jsonld-compacted` `@context`; a malformed entry throws. `format` (case-insensitive) is `'turtle'` (`'ttl'`/`'text/turtle'`), `'trig'` (`'application/trig'`), or **JSON-LD**: `'jsonld'` (`'json-ld'`/`'application/ld+json'`) emits the **expanded** form by default, and `'jsonld-expanded'` / `'jsonld-flattened'` / `'jsonld-compacted'` pick the [JSON-LD 1.1 document form](../data-formats/SKILL.md) explicitly. For JSON-LD `abbreviate` is **ignored** — IRI abbreviation is chosen by the `jsonld-compacted` form (which carries a prefix `@context`). An unrecognised `format` (or a malformed `prefixes`) throws. All three formats route through the SAME engine writer the native CLI/HTTP surface uses (so JS consumes the engine writer rather than hand-formatting JSON-LD). Compiled in only with the opt-in `serialize-rdf` bundle feature (see below); the lean bundle omits it. (JSON-LD serialise-OUT needs no extra feature — only `serialize-rdf`; the `jsonld` feature is INGEST-only.) **`jsonld-compacted` vs `serializeCompact` (full Compaction).** The wasm `serialize` `'jsonld-compacted'` form is the *prefix-only* `@context` (it abbreviates IRIs to `prefix:local` CURIEs from the `prefixes` map). For the **full W3C JSON-LD 1.1 Compaction Algorithm** against a caller-supplied `@context` (term definitions / `@vocab` / type-language-`@container` coercion / `@reverse` / `@id`/`@type` aliasing / value+node+IRI compaction), use the sibling **`serializeCompact(context, pretty, indent?)`** binding (sq-oy1f.5) — `context` is the `@context` **JSON text** (e.g. `'{"@vocab":"http://schema.org/"}'`), `pretty`/`indent` mirror `serialize`. It routes through `sparq_engine::serialize::graph_to_jsonld_compact` (still dependency-free, see the [data-formats SKILL](../data-formats/SKILL.md)) and is **lossless** (a JSON-LD→RDF round-trip reconstructs the triples). A non-object / malformed `context` throws. Same `serialize-rdf` bundle feature; absent on the lean bundle.
```js
// Full Compaction against a caller @context (NOT the prefix-only 'jsonld-compacted' form):
const doc = store.serializeCompact('{"@vocab":"http://schema.org/"}', true, ' ');
// → bare @vocab-relative predicate keys ("name", "knows"), the @context echoed.
```
```js
const ttl = store.serialize('turtle', true, ' ', true); // pretty Turtle, 2-space indent, default prefixes
const trig = store.serialize('trig', true, null, true); // pretty TriG over the whole dataset
const jsonld = store.serialize('jsonld-compacted', true, ' ', true); // pretty JSON-LD, compacted @context
// Caller-supplied prefix policy (e.g. the site's COMMON_PREFIXES → https://schema.org/, ex: → example.org):
const mine = store.serialize('turtle', true, ' ', true, [['ex', 'http://example.org/'], ['schema', 'https://schema.org/']]);
```
**Parse SHACL Compact Syntax (raw wasm `Store.parseShaclCompact`, scs bundle only).** `parseShaclCompact(text, base?)` parses a [SHACL Compact Syntax](https://www.w3.org/TR/shacl12-compact-syntax/) (SCS) document into the equivalent SHACL **shapes graph** and returns it as a pretty **Turtle string** — the SCS *input* direction (the `'Compact → shapes'` mode for the workbench). `base` (optional) is the base IRI relative IRIs and the `owl:Ontology` subject resolve against; `undefined`/`null` uses the SCS no-`BASE` convention (`urn:x-base:default`), and a document-level `BASE` directive overrides it. It reuses the `Store.serialize('turtle', true, ' ', true)` engine writer above (no second serialiser), so the bytes match that call; the shapes it yields validate data **identically** to the equivalent hand-written Turtle shapes (it is the same triples `validate` consumes), covering the grammar the W3C `shacl12-cs` corpus exercises. It is **stateless** (ignores the receiver's triples). A malformed SCS document throws a `JsError` carrying the 1-based source line.
```js
import init, { Store } from '@jeswr/sparq/wasm/sparq_wasm.js'; // the raw wasm Store
await init();
const store = Store.load('', 'turtle'); // stateless; receiver ignored
const shapesTurtle = store.parseShaclCompact(
'PREFIX ex: \nshapeClass ex:Person {\n ex:name xsd:string [1..1] .\n}\n');
// shapesTurtle is a pretty-Turtle shapes graph; feed it back to store.validate(...) or display it.
```
**EXPLAIN / EXPLAIN ANALYZE (query-plan introspection, raw wasm only).** Same plan text the Rust API (`sparq_engine::explain`) and the HTTP endpoint (`?explain` / `?explain=analyze`, or `Accept: text/x-sparq-explain`) return — returned to JS as a plain string. `explain` is a planning-only dry run (no execution; every query form); `explainAnalyze` runs the query (SELECT/ASK only) and appends a per-operator row-count trace.
```js
const plan = raw.explain('PREFIX ex: SELECT ?n ?a WHERE { ?s ex:name ?n . ?s ex:age ?a }');
// "EXPLAIN (SELECT) — planning-only dry run; nothing is executed.\n...Plan:\n ..."
const trace = raw.explainAnalyze('PREFIX ex: SELECT ?n WHERE { ?s ex:name ?n }');
// plan + per-operator output rows (wall times read 0 on wasm32 — no monotonic clock)
```
**Structured plan tree (`explainPlanJson` / `explainPlanAnalyzeJson`, explain-json bundle
only — the published bundle enables it; sq-ixc3.19).** The TYPED plan the GUI plan explorer
renders: `sparq-engine`'s `explain_json::PlanNode` as camelCase JSON — per operator
`{"operator", "estimated", "actual", "nanos", "qError", "children"}` (the sq-jbqh4 schema
contract, identical to the server's `Accept: application/x-sparq-explain+json` response).
The dry-run form populates only `estimated`; the analyze form (SELECT/ASK only) fills
`actual` rows and `qError` = max(est/actual, actual/est) exactly — `nanos` still reads 0 on
wasm32 (the same no-monotonic-clock caveat as `explainAnalyze`; real per-operator wall
times come from the desktop-native or server paths). `@sparq/client` exports the matching
`PlanNode` type + the `parsePlanJson` defensive parse.
```js
const tree = JSON.parse(raw.explainPlanAnalyzeJson('SELECT ?n WHERE { ?s ?n }'));
// { operator: "...", estimated: ..., actual: ..., nanos: 0, qError: ..., children: [...] }
```
**SHACL validation (`SparqStore.validate`, shipped by default).** `validate(data, shapes, format?)` validates an RDF **data graph** against a SHACL **shapes graph** and returns a typed `ValidationReport` (the JSON the wasm binding emits, parsed for you). It runs `sparq-shacl`'s SHACL Core + SHACL-SPARQL (`sh:sparql`) engine inside wasm — a drop-in for `rdf-validate-shacl`. It is **stateless** (does not consult the store's own triples). `format` defaults to `'turtle'` and accepts the same set as `fromString`.
```ts
import { SparqStore, type ValidationReport } from '@jeswr/sparq';
const store = await SparqStore.fromString('', 'turtle'); // validate ignores the receiver
const report: ValidationReport = store.validate(dataTurtle, shapesTurtle); // format defaults to 'turtle'
// ValidationReport = { conforms: boolean;
// results: Array<{ focusNode; path; value; sourceShape;
// sourceConstraintComponent; severity; message }> }
report.conforms; // false if ANY result (incl. Warning/Info)
const violations = report.results.filter(
r => r.severity === 'http://www.w3.org/ns/shacl#Violation'); // violations-only gate
```
The raw `Store.validate(data, shapes, format)` returns the same report as a JSON **string** (`JSON.parse` it yourself). `focusNode`/`value`/`sourceShape` are N-Triples term strings; `path` is a SHACL Turtle path expression; `severity`/`sourceConstraintComponent` are full IRIs; `message` is the first `sh:message` text (or a generated default). `path`/`value`/`message` are `null` when absent. Only a graph parse failure throws; malformed shapes are skipped, not surfaced. For large data graphs validate server-side via the `sparq-server` HTTP `validate` endpoint instead (the other half of the #162 decision). See the `shacl-validation` skill for the engine's SHACL coverage.
**Store-backed SHACL (raw wasm `Store.validateStore`, shacl bundle only, gh-2520).** `validateStore(shapes, format)` is the **stateful** counterpart: the data graph is the store's own contents — whatever `load`/`loadDataset`/`update`/`applyDelta` left in it — so only the *shapes* document is parsed per call. Report shape, `sh:conforms` semantics and error behaviour are identical to `validate`'s (only a shapes parse failure throws). Use it when one loaded store is re-validated as shapes are edited, instead of re-passing (and re-parsing) the data document every time.
```js
const store = Store.load(dataTurtle, 'turtle'); // parse the data ONCE
const report = JSON.parse(store.validateStore(shapesTurtle, 'turtle'));
```
Two caveats. It observes the store's **default graph** only — triples put in named graphs by `loadDataset` are not focus nodes or value nodes (`load` folds named graphs into the default graph, so a store built that way validates in full). And blank-node labels in `sourceShape` are minted fresh by each shapes parse, so they differ between any two calls (of either method) — treat them as per-call identifiers, not stable keys. The typed `SparqStore.validate` wrapper has no store-backed twin yet; reach for the raw `Store` for this one.
**Raw wasm `Store`: init (`initSync` vs async default), errors, and `.free()` (#1127).** The wasm-pack `--target web` glue (`../wasm/sparq_wasm.js`) is a real ESM module that exports a **default async `init`** plus a synchronous **`initSync`** — one of the two MUST run before any `Store.*` static (`SparqStore`/`Dataset` do this for you via the package's memoised `init()`; you only call these when using the raw `Store` directly).
```js
import init, { initSync, Store } from '@jeswr/sparq/wasm/sparq_wasm.js';
// (a) async default — the normal path. In the browser/Deno it fetches the .wasm
// relative to the module; pass explicit bytes/URL to override.
await init(); // or: await init({ module_or_path: bytes })
// (b) initSync — when you ALREADY hold the compiled module/bytes (no top-level await,
// e.g. a bundler that inlines the wasm, or a Cloudflare-Worker WebAssembly.Module import).
initSync({ module_or_path: wasmModuleOrBytes });
const store = Store.load(' .', 'ntriples');
```
- **When to use which.** Prefer the high-level `@jeswr/sparq` entry (`SparqStore`/`Dataset`), whose `init()` picks the right path per environment (Node reads the bytes off disk; browser/Deno `fetch`es) and memoises it — so the ~MB `.wasm` is paid at most once. Drop to `init`/`initSync` only when you import the raw `Store` glue directly: async `init()` for the common fetch-relative case, `initSync(...)` only when you have the module/bytes in hand and want no `await`.
- **`init()`/`initSync()` not called first → `Store.*` throws** a wasm-bindgen "must call init" error. Calling `init()` again is idempotent.
- **Format strings** for `Store.load`/`loadDataset`/`loadCompressed` are the same case-sensitive set the engine accepts: `turtle` (`ttl`/`text/turtle`), `ntriples` (`n-triples`/`nt`), `nquads` (`n-quads`/`nq`), `trig`, and `jsonld` (`json-ld`/`application/ld+json`, opt-in `jsonld` bundle). An **unrecognised format is an `Err`/throw** — it is NOT silently parsed as Turtle (so a `'jsonld'` load on the lean bundle throws rather than mis-parsing).
- **Errors are JS exceptions.** Every fallible `Store` method (`load*`, `query`, `ask`, `update`, `applyDelta`, `validate`, …) maps a Rust `Err(String)` to a thrown `Error` (wasm-bindgen `JsError`) carrying the engine message (parse error with position, malformed SPARQL, an unrecognised format, a query form routed to the wrong method — e.g. CONSTRUCT through `query`). Wrap calls in `try/catch`; there are no silent failures.
- **`.free()` — when and on what.** wasm linear memory is NOT GC'd: call `.free()` on every `Store` you create, AND on each cursor object (`QueryChunks` / the `queryCursor` / `queryQuadsChunks` handles) once drained or abandoned. After `.free()` the handle (and any cursor it spawned) must not be touched. In the high-level wrapper use `store.free()` or `using store = await SparqStore.from…()` (`Symbol.dispose`); for the raw `Store`, `break`ing out of a streaming `for…of` over a cursor still requires freeing that cursor. Leaking handles grows the 4 GB wasm heap until the tab/process OOMs.
## Gotchas / feature flags / prerequisites
- **ESM only, Node >= 18.** The package is `"type": "module"`; `init()` is idempotent and runs automatically on the first `SparqStore.from*` call (in Node it reads the wasm bytes from disk; in the browser/Deno it `fetch`es relative to the module). One runtime dep: `fzstd` (~8 KB, dynamically imported only when decoding zstd).
- **`SparqStore.query()` is SELECT/ASK only.** It returns `Bindings[]` (SELECT) or `boolean` (ASK); a CONSTRUCT/DESCRIBE routed through it throws. Use `queryQuads()` (RDF/JS `Quad`s) / `queryQuadsString()` (N-Triples) / `queryQuadsStream()` for the graph-valued forms. Federated (`SERVICE`) queries are still **not** exposed at the JS wrapper layer.
- **`REGEX` / `REPLACE` are compiled out** of the wasm build (the engine's non-default `regex` cargo feature is off to keep the bundle small). Use `CONTAINS`/`STRSTARTS`/`STRENDS`/... or a custom wasm build with `--features regex`.
- **SHACL is on `SparqStore.validate` (typed) AND raw `Store.validate` (JSON string), shipped by default.** The published bundle is built with `--features shacl`, so `validate` works out of the box. SHACL is **not free in the binary** — it pulls in the SHACL engine + `regex` + the `sh:sparql` query path, which roughly **doubles** the `.wasm` (measured ~1.21 MiB → ~2.19 MiB, +~1.0 MiB / +85%, pre-gzip). Size-sensitive consumers can build the lean variant (`npm run build:wasm:lean`, equivalently `wasm-pack build … --profile release-wasm` with no `--features`), which omits SHACL — `SparqStore.validate` then throws a clear "requires a SHACL-enabled wasm bundle" error. Use `--features shacl-af` to also compile `sh:rule`. Validation is in-process and best for small documents (~10–100 triples); large graphs should use the server-side HTTP `validate` path.
- **JSON-LD ingest (`'jsonld'`) is shipped in the published bundle but is an OPT-IN cargo feature.** The published `@jeswr/sparq` bundle is built with `--features shacl,jsonld` (the js `build:wasm` script), so `fromString(_, 'jsonld')` works out of the box. JSON-LD adds non-trivial binary size (linked via the `oxjsonld` parser), so the **lean default bundle** (`build:wasm:lean` / `cargo build -p sparq-wasm` with no `--features`) omits it to minimize overhead. On the lean bundle a `'jsonld'` load is not recognised as JSON-LD. Turtle / N-Triples / N-Quads / TriG are always present (no feature needed).
- **Remote-`@context` JSON-LD (`Store.loadJsonLdWithContexts`) needs the `jsonld-contexts` bundle feature ([SONNET-4.6] sq-yz27r, #3251).** Plain `'jsonld'` ingest drives `oxjsonld` with **no** `LoadDocumentCallback`, so a document that names its `@context` by URL rather than inline — which is how essentially every real Verifiable Credential is written (`"@context": "https://www.w3.org/2018/credentials/v1"`) — throws `No LoadDocumentCallback has been set to load remote contexts`. The opt-in `jsonld-contexts` feature (implies `jsonld`) adds `Store.loadJsonLdWithContexts(text, contexts)`, where `contexts` is an ordered `[[url, documentText], …]` array of context documents **the host has already retrieved**: `const ctx = await (await fetch(url)).text(); Store.loadJsonLdWithContexts(vcJson, [[url, ctx]])`. Nested/second-level remote contexts resolve through the same callback (it is `oxjsonld`'s own recursion, not a pre-parse rewrite of the document's `@context`). **The fetch stays in JS by necessity, not by preference** — `oxjsonld`'s `LoadDocumentCallback` is *synchronous* and cannot await `fetch`, so the split is host-fetches / binding-parses; the binding itself performs **no I/O** and the bundle links no HTTP code. **Fail-closed:** a `@context` URL the document references but `contexts` does not carry throws a `JsError` naming that URL (never a silent partial parse that would drop every term the context defines); the supplied map *is* the allowlist, so any same-origin / CSP policy is the host's to enforce at fetch time. Named graphs fold into the default graph, as `load` does. OFF by default so the lean `wasm_bundle_bytes` baseline is byte-identical; `build:wasm` does not yet enable it, and on a bundle without the feature the method is absent.
- **`serialize` / `dump` need the `serialize-rdf` bundle feature.** Exposed on BOTH the high-level `SparqStore.serialize(format?, opts?)` (with a `dump` alias) and the raw `Store.serialize(...)` ([OPUS-4.8] sq-u78ol / #1117 / #1129). The published `@jeswr/sparq` bundle is built with `--features shacl,jsonld,serialize-rdf` (the js `build:wasm` script), so `serialize(...)` works out of the box. It is **not free in the binary** — it links `sparq-engine`'s serializer matrix (the pretty Turtle / TriG writers) — so the **lean default bundle** (`build:wasm:lean` / `cargo build -p sparq-wasm` with no `--features`) omits it. On the lean bundle `SparqStore.serialize`/`dump` throw a clear "requires a serialize-rdf-enabled wasm bundle" error (and the raw `Store.serialize` method is absent).
- **`Store.parseShaclCompact` needs the `scs` bundle feature.** The published `@jeswr/sparq` bundle is built with `--features shacl,jsonld,serialize-rdf,scs` (the js `build:wasm` script), so `parseShaclCompact(...)` works out of the box. The `scs` feature implies `shacl` + `serialize-rdf` (it REUSES the `serialize` engine writer to emit the shapes Turtle — no second serialiser) and forwards to `sparq-shacl/scs` (a hand-rolled parser, **no new dependency**). The **lean default bundle** (`build:wasm:lean` / `cargo build -p sparq-wasm` with no `--features`) omits it, so the lean `.wasm` is unchanged; on the lean bundle the `parseShaclCompact` method is absent. (Raw `Store` only for now; the playground "Compact → shapes" input mode and any typed `SparqStore` wrapper are tracked separately.)
- **ODRL policy evaluation is an EXPERIMENTAL probe, NOT in the published bundle ([FABLE-5] sq-586sh, #890 ask A).** The opt-in `policy` cargo feature compiles `sparq-policy`'s stateless ODRL evaluator to wasm32 and exposes two probe free functions on the raw wasm surface — `policyEvaluate(policyRdf, format, action, target?, party?)` → decision JSON (`{allow, matchedRules, unmetConstraints}`, fail-closed: malformed policy throws, unmatched/empty policy denies) and `policyConflicts(policyRdf, format)` → static conflict/admissibility JSON. `build:wasm` does **not** enable it: the full JS API (per-dimension audit statuses, per-duty status, purpose/party taxonomies) awaits a maintainer public-contract decision (the sq-586sh report issue). The stateful `count-enforcement` feature is deliberately not forwarded (no cross-tab atomicity in a browser). See `usage-control-policy` for the evaluator semantics.
- **Byte-ingest (`Store.loadBytes` / `loadBytesWithBase`) needs the `bytes-ingest` bundle feature ([FABLE-5] sq-3ul2n.3).** The opt-in `bytes-ingest` cargo feature exposes `Store.loadBytes(bytes, format)` and `Store.loadBytesWithBase(bytes, format, base)`, which take the `Uint8Array` you already hold (e.g. `new Uint8Array(await response.arrayBuffer())`) and feed it to the SAME parse path as `load`/`loadWithBase`, skipping the UTF-16 JS-string round-trip. The result is byte-for-byte the store `Store.load(new TextDecoder().decode(bytes), format)` builds (equal size + probe-query JSON). Invalid UTF-8 is rejected **fail-closed** with a catchable `JsError` (RDF text formats are all UTF-8) — never a panic or lossy decode, the same error surface as a malformed document to `load`. ZERO new dependencies. OFF by default so the lean `wasm_bundle_bytes` baseline is byte-identical; the published bundle turns it on (the js `build:wasm` wiring is tracked separately, sq-3ul2n.5). On a bundle without the feature the `loadBytes` methods are absent.
- **SHACL-to-form derivation (`Store.deriveForm`) needs the `forms` bundle feature ([SONNET-4.6] sq-q4apb, #2396).** The opt-in `forms` cargo feature compiles `sparq-forms`' derivation to wasm32 and exposes `Store.deriveForm(data, shapes, focus, format, optionsJson)` on the raw wasm surface — the hosted-web half of the GUI forms bridge (`gui/app`'s `forms-bridge.ts` feature-detects exactly this method; desktop uses the Tauri `derive_form` command instead, and the adapter never falls through between hosts). Stateless one-shot: `data`/`shapes` are serialized workspace snapshots in `format` (named graphs preserved dataset-style; the workbench sends N-Quads), `focus` is an absolute IRI or `_:label`, `optionsJson` is the snake_case `{"mode":"edit"|"view","shape"?:iri-or-_:label}` object. Returns the `FormDescription` serde JSON **string** verbatim — byte-identical to the desktop bridge for the same inputs; `JSON.parse` it, never reconstruct keys/groups/widgets. Malformed graphs/focus/options throw a `JsError`; there is no demo-data fallback. OFF by default (the lean `wasm_bundle_bytes` baseline is byte-identical); `build:wasm` — the bundle the hosted /app, the site and the published package all consume — enables it ([SONNET-4.6] sq-q4apb, #2644), so `deriveForm` is present there and absent from `build:wasm:lean`. On a bundle without the feature the method is absent. See the `shacl-forms` skill for the derivation semantics.
- **`options.dataset` is not combinable with `options.compressed`** — there is no compressed dataset loader yet (the constructor throws). `compact-index` (3 permutations, ~half the memory) is auto-selected for wasm32 regardless; `compressed` adds block compression on top.
- **`size` / `heapBytes` report the DEFAULT graph only.** For dataset totals use `countQuads()` (its graph wildcard spans named graphs).
- **Mutation is overlay-based.** `update()` / `applyDelta()` write through an append-only delta overlay: the dictionary only grows, and deletes are tombstones until the wasm store is reloaded. Blank nodes in `applyDelta`/`removeQuads` are matched **by label** (so bnode triples can be retracted — impossible via SPARQL `DELETE DATA`).
- **Browser gzip truncation.** Browsers silently truncate **multi-member gzip** to the first member; `fromCompressed` uses `node:zlib` in Node (loops members) and `DecompressionStream` in the browser (single-member only). Multi-frame **zstd** decodes fully everywhere via fzstd. fzstd cannot decode zstd **dictionary** frames — for those supply a dict-capable decoder via `SparqDictionaryClient`'s `decodeWithDictionary` hook.
- **Lifetime.** Call `.free()` (or use `using`) to release wasm linear memory; the store and any held cursors must not be used afterward. wasm32 caps linear memory at 4 GB (a real tab is happier under ~2 GB): ~30 M triples raw, ~75 M with `compressed`.
- **Raw `Store` budget knobs are wasm-portable only.** `askWithMaxRows` bounds the working set by row count; the engine's wall-clock deadline budget is native-only (`std::time::Instant` is unusable on wasm32).
- **`explainAnalyze` wall times read 0 on wasm32.** There is no monotonic clock in the wasm bundle, so the per-operator trace reports 0 for every wall time; the per-operator **row counts are exact**. `explainAnalyze` executes the query (SELECT/ASK only) — CONSTRUCT/DESCRIBE/UPDATE are rejected; use `explain` (a non-executing dry run that accepts every query form) for those.
- **The bundle ships under the size-optimised `release-wasm` cargo profile ([OPUS-4.8] sq-7d3dj.1).** `build:wasm{,:lean}` build `wasm-pack --profile release-wasm` (root `Cargo.toml`): the COLD run-once parse crates (`spargebra`/`oxiri`/`oxttl`) compile at `opt-level = "z"` and local symbols are stripped (`strip = "symbols"`), while the HOT engine/core query-eval crates stay `opt-level 3` — so the bundle is materially smaller with no runtime-perf change (pure parser code, off every hot query path). The `wasm_bundle_bytes` perf-gate (`scripts/ci-bench.sh`) builds under the SAME cargo profile as the shipped bundle — it ratchets a raw `cargo build` `.wasm` (not the post-`wasm-bindgen`/`wasm-opt` npm artifact), so it tracks the profile the shipped bundle is built under rather than the shipped bytes themselves.
- **Benchmarking the bundle vs the JS/WASM ecosystem ([FABLE-5] sq-hmd7l.17).** `bench/wasm-compare/run.sh --bundle-only` is the DETERMINISTIC shipped-bundle-bytes comparison vs the pinned `oxigraph` npm artifact (the one wasm metric that can be canonical without a quiet box); `bench/wasm-compare/browser/` holds the per-phase browser harness (sq-3ul2n.1: Chromium/Firefox/WebKit + Node, shipped bundle only) and `compare.mjs`, the cross-library latency comparison (sparq vs oxigraph-npm vs N3.js+quadstore) on the same oracle-checked workload — no latency row without row-count agreement. Competitor packages are gather-only installs; first-read gap record `research/gap-wasm-2026-07.md`.
## See also
- `fused-decompress-parse`, `rust-parallel-parsing` — server/native ingest internals behind the codecs you feed `fromCompressed`.
- `hdt-format` — loading `.hdt` archives (native crate, not in the wasm bundle).
- `noir-circuit-patterns`, `noir-optimisation`, `mpc-protocols`, `verifiable-credentials-zk`, `sparql-formal-semantics` — the ZK/MPC estate (separate `zk` feature; not part of the JS/wasm surface).