@lde/pipeline 0.30.14 → 0.30.15

package/dist/guard/blankNodes.d.ts

@@ -0,0 +1,38 @@
+import type { Quad } from '@rdfjs/types';
+import type { QuadTransform } from '../stage.js';
+/**
+ * Why this guard exists.
+ *
+ * A file-based served store (e.g. the Dataset Knowledge Graph) rebuilds its
+ * index by concatenating every per-dataset n-quads file and parsing the
+ * concatenation as ONE RDF document (`qlever index` over
+ * `find … -exec cat {} +`). Blank-node labels are only document-scoped, and the
+ * pipeline emits deterministic labels (n3 `DataFactory.blankNode()` → `n3-N`,
+ * the counter resets per dataset/run), so the same label recurs across files and
+ * the indexer fuses those nodes into one — merging unrelated provenance,
+ * measurements and linksets across datasets and runs. Named nodes never fuse.
+ *
+ * The invariant for any quads the pipeline writes into such a store is therefore:
+ * NO blank nodes. Mint stable (skolem) IRIs instead — see `skolemIri` in
+ * `@lde/dataset`. These helpers make that invariant testable and enforceable.
+ *
+ * See ldelements/lde#474 and netwerk-digitaal-erfgoed/dataset-knowledge-graph#352.
+ */
+/**
+ * The distinct blank-node labels appearing in subject, object, or graph position
+ * across `quads`. Empty when the quads are blank-node-free.
+ */
+export declare function blankNodes(quads: Iterable<Quad>): string[];
+/**
+ * Throw if any quad carries a blank node. Use in producer tests to lock in the
+ * no-blank-nodes invariant (see module docs).
+ */
+export declare function assertNoBlankNodes(quads: Iterable<Quad>): void;
+/**
+ * A {@link QuadTransform} that passes quads through unchanged but throws on the
+ * first blank node it sees. Insert it just before the writer to turn the
+ * no-blank-nodes invariant into a hard pipeline failure (e.g. in a CI/staging
+ * run) rather than a per-test opt-in.
+ */
+export declare function failOnBlankNodes<Context>(): QuadTransform<Context>;
+//# sourceMappingURL=blankNodes.d.ts.map

package/dist/guard/blankNodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blankNodes.d.ts","sourceRoot":"","sources":["../../src/guard/blankNodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAU1D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAU9D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,KAAK,aAAa,CAAC,OAAO,CAAC,CAelE"}

package/dist/guard/blankNodes.js

@@ -0,0 +1,66 @@
+/**
+ * Why this guard exists.
+ *
+ * A file-based served store (e.g. the Dataset Knowledge Graph) rebuilds its
+ * index by concatenating every per-dataset n-quads file and parsing the
+ * concatenation as ONE RDF document (`qlever index` over
+ * `find … -exec cat {} +`). Blank-node labels are only document-scoped, and the
+ * pipeline emits deterministic labels (n3 `DataFactory.blankNode()` → `n3-N`,
+ * the counter resets per dataset/run), so the same label recurs across files and
+ * the indexer fuses those nodes into one — merging unrelated provenance,
+ * measurements and linksets across datasets and runs. Named nodes never fuse.
+ *
+ * The invariant for any quads the pipeline writes into such a store is therefore:
+ * NO blank nodes. Mint stable (skolem) IRIs instead — see `skolemIri` in
+ * `@lde/dataset`. These helpers make that invariant testable and enforceable.
+ *
+ * See ldelements/lde#474 and netwerk-digitaal-erfgoed/dataset-knowledge-graph#352.
+ */
+/**
+ * The distinct blank-node labels appearing in subject, object, or graph position
+ * across `quads`. Empty when the quads are blank-node-free.
+ */
+export function blankNodes(quads) {
+    const offenders = new Set();
+    for (const quad of quads) {
+        for (const term of [quad.subject, quad.object, quad.graph]) {
+            if (term.termType === 'BlankNode') {
+                offenders.add(term.value);
+            }
+        }
+    }
+    return [...offenders];
+}
+/**
+ * Throw if any quad carries a blank node. Use in producer tests to lock in the
+ * no-blank-nodes invariant (see module docs).
+ */
+export function assertNoBlankNodes(quads) {
+    const offenders = blankNodes(quads);
+    if (offenders.length > 0) {
+        throw new Error(`Output contains ${offenders.length} blank node(s), which fuse across ` +
+            `datasets when a file-based store cat-indexes per-dataset files. ` +
+            `Mint skolem IRIs instead (see skolemIri in @lde/dataset; ldelements/lde#474). ` +
+            `First: ${offenders.slice(0, 10).join(', ')}`);
+    }
+}
+/**
+ * A {@link QuadTransform} that passes quads through unchanged but throws on the
+ * first blank node it sees. Insert it just before the writer to turn the
+ * no-blank-nodes invariant into a hard pipeline failure (e.g. in a CI/staging
+ * run) rather than a per-test opt-in.
+ */
+export function failOnBlankNodes() {
+    return async function* (quads) {
+        for await (const quad of quads) {
+            for (const term of [quad.subject, quad.object, quad.graph]) {
+                if (term.termType === 'BlankNode') {
+                    throw new Error(`Blank node reached the writer (${term.value}); it would fuse ` +
+                        `across datasets in a cat-built index. Mint a skolem IRI instead ` +
+                        `(ldelements/lde#474): ${quad.subject.value} ${quad.predicate.value} …`);
+                }
+            }
+            yield quad;
+        }
+    };
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './progressReporter.js';
 export * from './selector.js';
 export * from './stage.js';
 export * from './stageOutputResolver.js';
+export * from './guard/blankNodes.js';
 export * from './sparql/index.js';
 export * from './distribution/index.js';
 export * from './provenance/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './progressReporter.js';
 export * from './selector.js';
 export * from './stage.js';
 export * from './stageOutputResolver.js';
+export * from './guard/blankNodes.js';
 export * from './sparql/index.js';
 export * from './distribution/index.js';
 export * from './provenance/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.30.14",
+  "version": "0.30.15",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/pipeline"