@metreeca/keep-sparql 0.10.0

package/dist/detect/index.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Detect-pass driver.
+ *
+ * Owns one `select` round per drain iteration covering every queued {@link Detect}. The cycle is:
+ *
+ *   **plan** → **encode** → `client.select` → **decode**
+ *
+ *  - the batch's candidate entries are collected;
+ *  - {@link encode} folds them into one batched existence `select`;
+ *  - `client.select` runs the unified query;
+ *  - {@link decode} folds the entries that came back into the present-entry set and resolves each
+ *    request to whether its entry is present.
+ *
+ * Variable allocation across the query is shared between {@link encode} and {@link decode} through
+ * a single {@link createScope | Scope}.
+ *
+ * @module
+ */
+import { createScope } from "@metreeca/core/scope";
+import { variable } from "@metreeca/wire-sparql";
+import { decode } from "./decode.js";
+import { encode } from "./encode.js";
+/**
+ * Per-batch body for the detect handler.
+ *
+ * Two phases run in sequence: **fetch** by folding the batch's candidate entries into one batched
+ * existence `select` through {@link encode} and running it; **deliver** by {@link decode | decoding}
+ * the solution to the present entries, folding them into a set, and resolving each request to whether
+ * its entry is present.
+ *
+ * @param batch The queued detect requests to resolve
+ * @param client The repository the existence query runs against
+ *
+ * @returns A promise settling once every request in the batch has been resolved
+ */
+export async function detect(batch, client) {
+    const scope = createScope(variable);
+    decode(scope, batch, await client.select(encode(scope, batch)));
+}
+//# sourceMappingURL=index.js.map

package/dist/detect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/detect/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAyB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC3B,KAAkC,EAClC,MAAwB;IAGxB,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAEpC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,CACvC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACpB,CAAC,CAAC;AAEJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SPARQL 1.1 repository connector.
+ *
+ * Composes a pluggable {@link Repository} into a fully-featured {@link Store} via
+ * {@link createSPARQLStore}, translating Store-level read and write operations into SPARQL queries and updates.
+ * Application developers select a ready-made connector (Oxigraph, HTTP, …) or implement {@link Repository}
+ * directly to support a new SPARQL backend.
+ *
+ * The SPARQL layer shared by every connector is defined in `@metreeca/wire-sparql`:
+ * {@link @metreeca/wire-sparql!SPARQL | SPARQL} text and {@link @metreeca/wire-sparql!Tuple | Tuple} solution rows.
+ * The RDF data model those rows carry is defined in `@metreeca/trio`: {@link @metreeca/trio!Triple | Triple}
+ * statements and {@link @metreeca/trio!Term | Term} values ({@link @metreeca/trio!Named | Named},
+ * {@link @metreeca/trio!Blank | Blank}, {@link @metreeca/trio!Tagged | Tagged}, {@link @metreeca/trio!Typed | Typed}),
+ * together with the {@link @metreeca/trio!named | named}/{@link @metreeca/trio!tagged |
+ * tagged}/{@link @metreeca/trio!typed | typed} constructors used to mint
+ * {@link @metreeca/trio!Term | Term} values from backend results.
+ *
+ * **Wiring a Connector**
+ *
+ * Pick a ready-made connector and feed it to {@link createSPARQLStore} to obtain a store:
+ *
+ * ```typescript
+ * import { createSPARQLStore } from "@metreeca/keep-sparql";
+ * import { createOxiRepository } from "@metreeca/wire-sparql-oxigraph";
+ *
+ * const store = createSPARQLStore(createOxiRepository());
+ *
+ * await store.create({
+ *     entry: "http://example.com/products/1",
+ *     shape: ProductShape,
+ *     state: { name: "Widget", price: 9.99 }
+ * });
+ * ```
+ *
+ * **Implementing a Connector**
+ *
+ * To support a new SPARQL backend, implement a {@link @metreeca/wire-sparql!Repository | Repository} and use
+ * {@link @metreeca/trio!named | named}, {@link @metreeca/trio!tagged | tagged}, and
+ * {@link @metreeca/trio!typed | typed} to lift backend node values into the shared
+ * {@link @metreeca/trio!Term | Term} representation. The reference implementation in
+ * `@metreeca/wire-sparql-oxigraph` exemplifies the pattern:
+ *
+ * ```typescript
+ * import { named, tagged, type Term, typed } from "@metreeca/trio";
+ * import { type Repository } from "@metreeca/wire-sparql";
+ *
+ * function decode(node: BackendNode): Term {
+ *     return node.kind === "iri" ? named(node.iri)
+ *         : node.kind === "language" ? tagged(node.text, node.language)
+ *             : typed(node.text, node.datatype);
+ * }
+ *
+ * export function createMyRepository(): Repository {
+ *     // ... satisfy ask/select/construct/update/execute/close against the backend
+ * }
+ * ```
+ *
+ * @see {@link https://www.w3.org/TR/sparql11-query/ SPARQL 1.1 Query Language}
+ * @see {@link https://www.w3.org/TR/sparql11-update/ SPARQL 1.1 Update}
+ * @see {@link https://www.w3.org/TR/rdf11-concepts/ RDF 1.1 Concepts and Abstract Syntax}
+ *
+ * @group Connectors
+ *
+ * @module index
+ */
+import type { Store } from "@metreeca/keep";
+import { type Repository } from "@metreeca/wire-sparql";
+/**
+ * Creates a SPARQL store backed by a {@link Repository}.
+ *
+ * Each StoreClient call (standalone or inside {@link Store.execute execute}) is dispatched through a fresh
+ * {@link Repository} scope obtained from {@link Repository.execute repository.execute}, so concurrent calls share no
+ * transaction. Inside {@link Store.execute execute}, the user task receives a StoreClient wired to the scoped
+ * Repository; mutations are batched and flushed to the repository as a single update when the task completes, then
+ * committed by the repository transaction. Queries within the task do not observe the task's own pending mutations
+ * (no read-your-own-writes); split dependent reads across separate `execute` calls.
+ *
+ * > [!IMPORTANT]
+ * > **Transaction Isolation** — Determined by the supplied {@link Repository}.
+ *
+ * > [!IMPORTANT]
+ * > **Mutation Events** — Limited to mutations issued through this store; mutations from other clients on the
+ * > underlying repository are not observed.
+ *
+ * > [!IMPORTANT]
+ * > Updates issued within `execute` are always buffered and flushed as a single update on commit, regardless of
+ * > native transaction support. Native transactions remain relevant nonetheless, isolating the task's reads
+ * > for consistency.
+ *
+ * @param repository - The repository for SPARQL query, update, and transaction execution
+ *
+ * @returns An immutable {@link Store}
+ */
+export declare function createSPARQLStore(repository: Repository): Store;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,gBAAgB,CAAC;AAKzD,OAAO,EAGN,KAAK,UAAU,EAEf,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,KAAK,CAgC/D"}

package/dist/index.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createBatchingStore } from "@metreeca/keep/batching";
+import { createManagingStore } from "@metreeca/keep/managing";
+import { createValidatingStore } from "@metreeca/keep/validating";
+import { log } from "@metreeca/tape";
+import { createBufferingRepository, createLoggingRepository } from "@metreeca/wire-sparql";
+import { detect } from "./detect/index.js";
+import { lookup } from "./lookup/index.js";
+import { modify } from "./modify/index.js";
+import { select } from "./select/index.js";
+const logger = log(import.meta.url);
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Creates a SPARQL store backed by a {@link Repository}.
+ *
+ * Each StoreClient call (standalone or inside {@link Store.execute execute}) is dispatched through a fresh
+ * {@link Repository} scope obtained from {@link Repository.execute repository.execute}, so concurrent calls share no
+ * transaction. Inside {@link Store.execute execute}, the user task receives a StoreClient wired to the scoped
+ * Repository; mutations are batched and flushed to the repository as a single update when the task completes, then
+ * committed by the repository transaction. Queries within the task do not observe the task's own pending mutations
+ * (no read-your-own-writes); split dependent reads across separate `execute` calls.
+ *
+ * > [!IMPORTANT]
+ * > **Transaction Isolation** — Determined by the supplied {@link Repository}.
+ *
+ * > [!IMPORTANT]
+ * > **Mutation Events** — Limited to mutations issued through this store; mutations from other clients on the
+ * > underlying repository are not observed.
+ *
+ * > [!IMPORTANT]
+ * > Updates issued within `execute` are always buffered and flushed as a single update on commit, regardless of
+ * > native transaction support. Native transactions remain relevant nonetheless, isolating the task's reads
+ * > for consistency.
+ *
+ * @param repository - The repository for SPARQL query, update, and transaction execution
+ *
+ * @returns An immutable {@link Store}
+ */
+export function createSPARQLStore(repository) {
+    const buffering = createBufferingRepository(createLoggingRepository(repository, message => logger.debug `${message}`));
+    return createManagingStore(store(buffering), {
+        execute: task => buffering.execute(repository => task(store(repository))),
+        close: () => buffering.close()
+    });
+    function store(client) {
+        return createValidatingStore(createBatchingStore({
+            detect: (batch) => detect(batch, client),
+            lookup: (batch, broker) => lookup(batch, client, broker),
+            select: (batch, broker) => select(batch, client, broker),
+            modify: (batch) => modify(batch, client)
+        }), {
+            trusted: true
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EACN,yBAAyB,EACzB,uBAAuB,EAGvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAGpC,wHAAwH;AAExH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IAEvD,MAAM,SAAS,GAAG,yBAAyB,CAC1C,uBAAuB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAA,GAAG,OAAO,EAAE,CAAC,CACxE,CAAC;IAGF,OAAO,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;QAE5C,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;QACzE,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE;KAE9B,CAAC,CAAC;IAGH,SAAS,KAAK,CAAC,MAAwB;QAEtC,OAAO,qBAAqB,CAAC,mBAAmB,CAAC;YAEhD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;YACxC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;YACxD,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;YACxD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;SAExC,CAAC,EAAE;YAEH,OAAO,EAAE,IAAI;SAEb,CAAC,CAAC;IAEJ,CAAC;AAEF,CAAC"}

package/dist/lookup/decode.d.ts

@@ -0,0 +1,33 @@
+import type { Scope } from "@metreeca/core/scope";
+import { type Flake } from "@metreeca/keep-flake";
+import type { Broker, Deferred, Lookup } from "@metreeca/keep/batching";
+import type { Tuple, Variable } from "@metreeca/wire-sparql";
+/**
+ * Decodes a SELECT result tuple set into a resource state.
+ *
+ * Reads back the arms the emitter produced, walking the same {@link Flake | lookup plan} and resolving
+ * each property from its column in the returned `tuples` through the shared {@link Scope}. Each property
+ * is read by the counterpart of the arm that emitted it:
+ *
+ *  - a **scalar** property reads its column and recurses into the nested subject as an embedded or
+ *    expanded resource;
+ *  - a **localised** property collects every tagged term across its arm's rows into a tag-keyed
+ *    dictionary or the shorthand the model requests;
+ *  - a **variant** property reads whichever requested variant's column bound ({@link getUnionPlaceholders},
+ *    union.md §Model), fixing the variant by the bound column with no term classification: the read-side
+ *    dual of the emitter's membership gate.
+ *
+ * Properties with no emitted column resolve inline: set-valued properties forward to the collections
+ * pass through {@link select}, and `id` / `type` markers read from the focus and shape. Each item's
+ * deferred settles with its decoded resource, or rejects with a `TypeError` on a malformed tuple set
+ * that breaches the shape contract write-time validation upholds.
+ *
+ * @param scope The variable scope shared with the encoder
+ * @param items The batched requests, each paired with its {@link Flake | lookup plan} and deferred
+ * @param broker The cross-pass channel forwarding set-valued slots to the collections pass
+ * @param tuples The solution rows returned by the batched SELECT query
+ */
+export declare function decode(scope: Scope<Variable>, items: readonly (Deferred<Lookup> & {
+    readonly flake: Flake;
+})[], broker: Broker, tuples: readonly Tuple[]): void;
+//# sourceMappingURL=decode.d.ts.map

package/dist/lookup/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/lookup/decode.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAEN,KAAK,KAAK,EAKV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIxE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAK7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EACtB,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,EAAE,EAChE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,KAAK,EAAE,GACtB,IAAI,CA2PN"}

package/dist/lookup/decode.js

@@ -0,0 +1,193 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getShapeVariants } from "@metreeca/blue/union";
+import { eager } from "@metreeca/blue/value";
+import { isAny, isArray, isObject } from "@metreeca/core";
+import { unique } from "@metreeca/core/arrays";
+import { matchTag } from "@metreeca/core/language";
+import { equals } from "@metreeca/core/structures";
+import { getFlakeEntries, getFlakeVariant, isModelBranch, isQueryBranch } from "@metreeca/keep-flake";
+import { isTemplate } from "@metreeca/qest/template";
+import { column } from "../_/_decode.js";
+import { getUnionPlaceholders } from "../_/_union.js";
+/**
+ * Decodes a SELECT result tuple set into a resource state.
+ *
+ * Reads back the arms the emitter produced, walking the same {@link Flake | lookup plan} and resolving
+ * each property from its column in the returned `tuples` through the shared {@link Scope}. Each property
+ * is read by the counterpart of the arm that emitted it:
+ *
+ *  - a **scalar** property reads its column and recurses into the nested subject as an embedded or
+ *    expanded resource;
+ *  - a **localised** property collects every tagged term across its arm's rows into a tag-keyed
+ *    dictionary or the shorthand the model requests;
+ *  - a **variant** property reads whichever requested variant's column bound ({@link getUnionPlaceholders},
+ *    union.md §Model), fixing the variant by the bound column with no term classification: the read-side
+ *    dual of the emitter's membership gate.
+ *
+ * Properties with no emitted column resolve inline: set-valued properties forward to the collections
+ * pass through {@link select}, and `id` / `type` markers read from the focus and shape. Each item's
+ * deferred settles with its decoded resource, or rejects with a `TypeError` on a malformed tuple set
+ * that breaches the shape contract write-time validation upholds.
+ *
+ * @param scope The variable scope shared with the encoder
+ * @param items The batched requests, each paired with its {@link Flake | lookup plan} and deferred
+ * @param broker The cross-pass channel forwarding set-valued slots to the collections pass
+ * @param tuples The solution rows returned by the batched SELECT query
+ */
+export function decode(scope, items, broker, tuples) {
+    items.forEach(({ request, flake, resolve, reject }) => decodeResource(request.entry, flake, request.locale)
+        .then(resolve)
+        .catch(reject));
+    function decodeResource(entry, flake, locale) {
+        return Promise.all(flake.range.variants.flatMap(variant => variant.kind !== "resource" ? [] : [decodeVariant(entry, variant, locale, getFlakeVariant(flake, variant))])).then(resources => resources.reduce((merged, resource) => ({ ...merged, ...resource }), {}));
+    }
+    function decodeVariant(entry, shape, locale, branches) {
+        return Promise.all(branches.map((branch) => {
+            // a value set resolving to no content is never surfaced as an empty array or map (§4):
+            // the owning property is omitted from the decoded resource instead, except on a
+            // constrained collection (a query tuple carrying a selection), whose value is the
+            // filtered result set and legitimately empty
+            return isQueryBranch(branch) ? broker
+                .select({ entry, shape, field: branch.entry, query: branch.drain.mould, locale })
+                .then(values => [branch.path[branch.path.length - 1], isSelected(branch.drain.mould) || !isEmpty(values) ? values : undefined])
+                : isModelBranch(branch) ? Promise
+                    .resolve(decodeProperty(locale, branch))
+                    .then(value => [branch.path[branch.path.length - 1], value])
+                    : branch.entry.kind === "id" ? [branch.path[branch.path.length - 1], entry]
+                        : [branch.path[branch.path.length - 1], shape.class];
+        })).then(slots => slots.reduce((resource, [key, value]) => value === undefined ? resource : { ...resource, [key]: value }, {}));
+    }
+    /**
+     * Reads a single-valued model property, dispatching by range kind in the emitter's order: a **union** to
+     * {@link decodeUnion}, a **localised** `dictionary` leaf to {@link decodeDictionary}, any other **scalar**
+     * shape to {@link decodeValue}. The property is single-valued, so the first decoded value stands; an empty
+     * result omits the owning property (§4).
+     */
+    function decodeProperty(locale, branch) {
+        const rangeShape = branch.entry.range.shape;
+        const model = branch.drain?.mould;
+        if (rangeShape.kind === "union") {
+            return decodeUnion(rangeShape, locale, branch, model)[0];
+        }
+        else if (rangeShape.kind === "dictionary") {
+            // localised slots resolve as a single structured `Localised` value, not a collection:
+            // the `Locales` placeholder's tag ranges select the languages and fix the per-tag cardinality
+            return decodeDictionary(locale, model, unique(column(scope.resolve(branch), tuples), equals));
+        }
+        else {
+            return decodeValue(rangeShape, locale, getFlakeEntries(branch), model, unique(column(scope.resolve(branch), tuples), equals))[0];
+        }
+    }
+    /**
+     * Decodes the localised arm: the language-tagged terms matched against a localised placeholder.
+     *
+     * Structural access (a {@link @metreeca/qest/template!Locales | Locales} placeholder) yields the
+     * {@link Dictionary} map of the tags matching the requested ranges by RFC 4647 basic filtering (the wildcard `*`
+     * or an empty map admits every tag), with the per-tag cardinality fixed by the placeholder's value shape. Coalesced
+     * access (a plain string or singleton-array placeholder) reduces the map to the first locale-priority
+     * tag present (§6.2), at the matching per-tag cardinality. A typed literal carrying no language tag
+     * lands under the `und` tag. A result carrying no content resolves to `undefined`, so the owning
+     * property is omitted (§4).
+     */
+    function decodeDictionary(locale, placeholder, terms) {
+        const pairs = terms.flatMap((t) => {
+            return t.kind === "blank" || t.kind === "named" ? []
+                : t.kind === "tagged" ? [{ tag: t.language === "" ? "und" : t.language, text: t.text }]
+                    : [{ tag: "und", text: t.text }];
+        });
+        if (isObject(placeholder)) {
+            const ranges = Object.keys(placeholder);
+            const matching = ranges.length === 0 ? pairs : pairs.filter(({ tag }) => ranges.some(range => matchTag(tag, range)));
+            if (matching.length === 0) {
+                return undefined;
+            }
+            else if (Object.values(placeholder).some(v => isArray(v))) {
+                return matching.reduce((values, { tag, text }) => ({ ...values, [tag]: [...(values[tag] ?? []), text] }), {});
+            }
+            else {
+                return matching.reduce((values, { tag, text }) => ({ ...values, [tag]: text }), {});
+            }
+        }
+        else {
+            const winning = locale.find(tag => pairs.some(pair => pair.tag === tag));
+            const texts = pairs.filter(pair => pair.tag === winning).map(pair => pair.text);
+            return winning === undefined ? undefined
+                : isArray(placeholder) ? texts
+                    : texts[0];
+        }
+    }
+    /**
+     * Decodes the variant arms, the read-side dual of the emitter's membership gate: each requested variant
+     * owns its own arm and object column, so the value's variant is fixed by which column bound, with no
+     * term classification (union.md §Model). The property is single-valued, so the first requested variant
+     * whose column is bound stands; same-kind variants decode an identical bare payload. Resolves to no
+     * value when no variant column bound, omitting the owning property (§4).
+     */
+    function decodeUnion(shape, locale, branch, placeholder) {
+        const variants = getShapeVariants(shape);
+        const requested = getUnionPlaceholders(variants, placeholder);
+        const present = variants.find((variant) => variant.kind !== "dictionary" && requested.has(variant) && unique(column(scope.resolve(variant), tuples), equals).length > 0);
+        return present === undefined ? []
+            : decodeValue(present, locale, getFlakeVariant(branch, present), requested.get(present), unique(column(scope.resolve(present), tuples), equals));
+    }
+    /**
+     * Coerces a bound column into values of `shape`, shared by the scalar and variant readers: literal
+     * shapes map each typed term to its JavaScript value; a `reference` yields bare {@link Reference}s, or
+     * expands them as nested resources when the placeholder is a template; a `resource` always expands.
+     */
+    function decodeValue(shape, locale, branches, placeholder, terms) {
+        switch (shape.kind) {
+            case "boolean":
+                return terms.filter(t => t.kind === "typed").map(t => t.text === "true");
+            case "number":
+                return terms.filter(t => t.kind === "typed").map(t => Number(t.text));
+            case "string":
+                return terms.filter(t => t.kind === "typed").map(t => t.text);
+            case "reference":
+                return isTemplate(placeholder)
+                    ? entries().map(entry => decodeVariant(entry, eager(shape.shape), locale, branches))
+                    : entries();
+            case "resource":
+                return entries().map(entry => decodeVariant(entry, shape, locale, branches));
+        }
+        /**
+         * The IRIs bound by the column, the named terms of a reference- or resource-ranged property.
+         */
+        function entries() {
+            return terms.filter(t => t.kind === "named").map(t => t.iri);
+        }
+    }
+    /**
+     * Tests whether a resolved slot value carries no content (`undefined`, an empty array, or an empty
+     * map) and must therefore be omitted from the decoded resource (§4).
+     */
+    function isEmpty(value) {
+        return value === undefined
+            || isArray(value, [])
+            || isObject(value, {});
+    }
+    /**
+     * Tests whether a collection query carries a non-vacuous selection: such a slot is a filtered query
+     * whose result set is returned even when empty, rather than an unconstrained value set subject to
+     * empty-value omission (§4).
+     */
+    function isSelected(query) {
+        return isArray(query, [isAny, selection => isObject(selection) && Object.keys(selection).length > 0
+        ]);
+    }
+}
+//# sourceMappingURL=decode.js.map

package/dist/lookup/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/lookup/decode.ts"],"names":[],"mappings":"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"}

package/dist/lookup/encode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resources-pass SPARQL emitter.
+ *
+ * Folds every batched request's {@link Flake | lookup plan} into one `SELECT` whose `WHERE` is a
+ * `UNION` of arms. `UNION` sums solutions rather than joining them, so giving each fan-out source its
+ * own arm keeps the row count a sum of per-slot cardinalities instead of a cross-product. Set-valued
+ * properties go to the collections pass, so this pass sees only single-valued slots and the only
+ * fan-out sources are localised (`dictionary`) leaves and union variants.
+ *
+ * A resource contributes two descents, {@link scalars} and {@link composites}, together emitting three
+ * arm kinds:
+ *
+ *  - a **scalar** arm (from {@link scalars}): the whole plain single-valued subtree (scalars, references,
+ *    embedded resources), every edge `OPTIONAL` so one row carries all bound slots;
+ *  - a **localised** arm per `dictionary` leaf (from {@link composites}): the required path to the leaf's
+ *    parent, then the localised edge binding one tagged-term column;
+ *  - a **variant** arm per requested union variant (from {@link composites}; {@link getUnionPlaceholders},
+ *    union.md §Model): the variant's object column gated by its {@link membership} constraint, then the
+ *    variant's subtree.
+ *
+ * Variables come from the shared {@link Scope}, keyed on {@link Branch} identity (or the variant shape
+ * for a variant column), so the decoder recovers each column by resolving the same node. Requests whose
+ * flake has no descent branch contribute no arm and are pre-filtered by the caller.
+ *
+ * @module
+ */
+import type { Scope } from "@metreeca/core/scope";
+import { type Flake } from "@metreeca/keep-flake";
+import type { Lookup } from "@metreeca/keep/batching";
+import { type SPARQL, type Variable } from "@metreeca/wire-sparql";
+/**
+ * Emits one batched SELECT covering every request.
+ *
+ * Builds the `WHERE` from the `UNION` of every request's arms, all sharing `scope` so the decoder can
+ * recover each request's columns.
+ *
+ * @param scope The variable allocator shared with the decoder, keyed on {@link Branch} identity
+ * @param batch The root entries paired with their {@link Flake | lookup plans}
+ *
+ * @returns The unified SELECT query
+ */
+export declare function encode(scope: Scope<Variable>, batch: readonly {
+    readonly request: Lookup;
+    readonly flake: Flake;
+}[]): SPARQL;
+//# sourceMappingURL=encode.d.ts.map

package/dist/lookup/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/lookup/encode.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAe,KAAK,KAAK,EAAmD,MAAM,sBAAsB,CAAC;AAChH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAMnE;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EACtB,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,EAAE,GACnE,MAAM,CA4HR"}

package/dist/lookup/encode.js

@@ -0,0 +1,111 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getFlakeEntries, getFlakeVariant, isModelBranch } from "@metreeca/keep-flake";
+import { named } from "@metreeca/trio";
+import { all, fragment, optional, select, union, where } from "@metreeca/wire-sparql/builder";
+import { link, membership } from "../_/_encode.js";
+import { getUnionPlaceholders } from "../_/_union.js";
+/**
+ * Emits one batched SELECT covering every request.
+ *
+ * Builds the `WHERE` from the `UNION` of every request's arms, all sharing `scope` so the decoder can
+ * recover each request's columns.
+ *
+ * @param scope The variable allocator shared with the decoder, keyed on {@link Branch} identity
+ * @param batch The root entries paired with their {@link Flake | lookup plans}
+ *
+ * @returns The unified SELECT query
+ */
+export function encode(scope, batch) {
+    return select(all(), where(union(...batch.flatMap(({ request, flake }) => resource([], named(request.entry), getFlakeEntries(flake))))));
+    /**
+     * The arms reading the subtree at `anchor`. A resource has two descents, its {@link scalars} and its
+     * {@link composites}, each an independent arm of the enclosing `UNION` and each prefixed by `path`:
+     * the required edges reaching `anchor`, empty at the root, a variant's membership-gated reach in
+     * recursion.
+     */
+    function resource(path, anchor, entries) {
+        return [
+            ...scalars(path, anchor, entries),
+            ...composites(path, anchor, entries)
+        ];
+    }
+    /**
+     * The single arm reading `anchor`'s scalar properties: `path` followed by the `OPTIONAL` block of the
+     * plain single-valued subtree. Emitted only when non-empty, so a bare `path` still binds the edges
+     * reaching `anchor` even when it has no scalar leaf.
+     */
+    function scalars(path, anchor, entries) {
+        return arm(...path, ...optionals(anchor, entries));
+        /**
+         * The `OPTIONAL` clauses of the plain single-valued subtree at `anchor`, one per branch wrapping its
+         * edge and nested descent. Composite branches (`dictionary` leaves, unions) are skipped:
+         * {@link composites} emits them as standalone arms.
+         */
+        function optionals(anchor, entries) {
+            return entries.filter(isModelBranch).flatMap(branch => {
+                const shape = branch.entry.range.shape;
+                if (shape.kind === "dictionary" || shape.kind === "union") {
+                    return [];
+                }
+                else {
+                    const target = scope.resolve(branch);
+                    return [optional(link([anchor, branch.entry, target]), ...optionals(target, getFlakeEntries(branch)))];
+                }
+            });
+        }
+    }
+    /**
+     * The standalone composite arms under `anchor`, the complement of {@link scalars}: one arm per
+     * `dictionary` leaf, one per requested union variant (each with its own subtree and nested composites), recursing
+     * through plain nested resources. Each arm carries `path` (the required edges reaching here) so it
+     * yields rows only when that path exists.
+     */
+    function composites(path, anchor, entries) {
+        return entries.filter(isModelBranch).flatMap(branch => {
+            const shape = branch.entry.range.shape;
+            if (shape.kind === "union") {
+                return [...getUnionPlaceholders(shape.variants, branch.drain?.mould).keys()].flatMap(variant => {
+                    const target = scope.resolve(variant);
+                    return resource([
+                        ...path,
+                        link([anchor, branch.entry, target]),
+                        membership(target, variant)
+                    ], target, getFlakeVariant(branch, variant));
+                });
+            }
+            else if (shape.kind === "dictionary") {
+                const target = scope.resolve(branch);
+                return arm(...path, link([anchor, branch.entry, target]));
+            }
+            else {
+                const target = scope.resolve(branch);
+                return composites([
+                    ...path,
+                    link([anchor, branch.entry, target])
+                ], target, getFlakeEntries(branch));
+            }
+        });
+    }
+    /**
+     * An arm wrapping `clauses`, or nothing when there are none: an empty {@link fragment} would surface
+     * as a stray `{ }` branch matching everything once the enclosing {@link union} groups the arms.
+     */
+    function arm(...clauses) {
+        return clauses.length > 0 ? [fragment(...clauses)] : [];
+    }
+}
+//# sourceMappingURL=encode.js.map