@lde/pipeline 0.31.5 → 0.32.0

package/dist/writer/fileWriter.d.ts

@@ -1,6 +1,5 @@
 import { Dataset } from '@lde/dataset';
-import type { Quad } from '@rdfjs/types';
-import { Writer } from './writer.js';
+import { RunContext, RunWriter, Writer } from './writer.js';
 export interface FileWriterOptions {
     /**
      * Output directory for written files.
@@ -32,21 +31,47 @@ export interface FileWriterOptions {
      */
     graphIri?: (dataset: Dataset) => URL;
 }
+/**
+ * The run writer a {@link FileWriter} opens: per-dataset `flush` and `reset`
+ * are always available, so direct callers need no optional chaining.
+ */
+export interface FileRunWriter extends RunWriter {
+    flush(dataset: Dataset): Promise<void>;
+    reset(dataset: Dataset): Promise<void>;
+}
+/**
+ * Streams RDF quads to files on disk using N3 Writer.
+ *
+ * Files are named based on the dataset IRI using filenamify-url.
+ *
+ * Within a run ({@link openRun}), a single N3Writer is kept open per dataset
+ * across all `write` calls, so Turtle prefix declarations are written once and
+ * triples can be grouped by subject. `flush` finalizes a dataset's file;
+ * `commit` finalizes any files still open, and `abort` discards their
+ * temporary output, leaving no half-written final file behind.
+ */
 export declare class FileWriter implements Writer {
     private readonly outputDir;
     readonly format: 'turtle' | 'n-triples' | 'n-quads';
     private readonly replacementCharacter;
     private readonly prefixes?;
     private readonly graphIri?;
-    private readonly activeWriters;
     constructor(options: FileWriterOptions);
-    write(dataset: Dataset, quads: AsyncIterable<Quad>): Promise<void>;
-    flush(dataset: Dataset): Promise<void>;
-    reset(dataset: Dataset): Promise<void>;
+    openRun(_context?: RunContext): Promise<FileRunWriter>;
+    private writeQuads;
+    private flushFile;
+    private flushPath;
+    private discardFile;
+    /**
+     * Close an open file's stream and remove its temp file. Await the stream
+     * closing before removing: the write stream opens its fd lazily, so a
+     * pending open could otherwise recreate the file after rm() ran.
+     */
+    private closeAndRemove;
     getOutputPath(dataset: Dataset): string;
     getFilename(dataset: Dataset): string;
     private getFilePath;
-    private getOrCreateWriter;
+    private getOrCreateFile;
     private getExtension;
 }
 //# sourceMappingURL=fileWriter.d.ts.map

package/dist/writer/fileWriter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fileWriter.d.ts","sourceRoot":"","sources":["../../src/writer/fileWriter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAMzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;CACtC;AAiBD,qBAAa,UAAW,YAAW,MAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG1B;gBAEQ,OAAO,EAAE,iBAAiB;IAQhC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BtC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB5C,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAIvC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAQrC,OAAO,CAAC,WAAW;YAIL,iBAAiB;IA4B/B,OAAO,CAAC,YAAY;CAUrB"}
+{"version":3,"file":"fileWriter.d.ts","sourceRoot":"","sources":["../../src/writer/fileWriter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAOvC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;CACtC;AAgBD;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA4B;gBAE1C,OAAO,EAAE,iBAAiB;IAQhC,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;YAwB9C,UAAU;YAqCV,SAAS;YAOT,SAAS;YAgCT,WAAW;IAczB;;;;OAIG;YACW,cAAc;IAQ5B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAIvC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAQrC,OAAO,CAAC,WAAW;YAIL,eAAe;IA6B7B,OAAO,CAAC,YAAY;CAUrB"}

package/dist/writer/fileWriter.js

@@ -3,27 +3,28 @@ import { mkdir, rename, rm } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import filenamifyUrl from 'filenamify-url';
 import { DataFactory, Writer as N3Writer } from 'n3';
+const formatMap = {
+    turtle: 'Turtle',
+    'n-triples': 'N-Triples',
+    'n-quads': 'N-Quads',
+};
 /**
  * Streams RDF quads to files on disk using N3 Writer.
  *
  * Files are named based on the dataset IRI using filenamify-url.
  *
- * A single N3Writer is kept open per dataset across all {@link write} calls,
- * so Turtle prefix declarations are written once and triples can be grouped
- * by subject. Call {@link flush} after all stages complete to finalize the file.
+ * Within a run ({@link openRun}), a single N3Writer is kept open per dataset
+ * across all `write` calls, so Turtle prefix declarations are written once and
+ * triples can be grouped by subject. `flush` finalizes a dataset's file;
+ * `commit` finalizes any files still open, and `abort` discards their
+ * temporary output, leaving no half-written final file behind.
  */
-const formatMap = {
-    turtle: 'Turtle',
-    'n-triples': 'N-Triples',
-    'n-quads': 'N-Quads',
-};
 export class FileWriter {
     outputDir;
     format;
     replacementCharacter;
     prefixes;
     graphIri;
-    activeWriters = new Map();
     constructor(options) {
         this.outputDir = options.outputDir;
         this.format = options.format ?? 'n-triples';
@@ -31,13 +32,36 @@ export class FileWriter {
         this.prefixes = options.prefixes;
         this.graphIri = options.graphIri;
     }
-    async write(dataset, quads) {
+    async openRun(_context) {
+        const openFiles = new Map();
+        return {
+            write: (dataset, quads) => this.writeQuads(openFiles, dataset, quads),
+            flush: (dataset) => this.flushFile(openFiles, dataset),
+            reset: (dataset) => this.discardFile(openFiles, dataset),
+            commit: async () => {
+                // Finalize files not yet flushed per dataset – a safety net so a
+                // committed run never leaves a complete output stuck in a temp file.
+                for (const { finalPath } of openFiles.values()) {
+                    await this.flushPath(openFiles, finalPath);
+                }
+            },
+            abort: async () => {
+                // Discard all temp output: a crash or abort leaves at most a stale
+                // `*.tmp`, never a truncated final file.
+                for (const openFile of openFiles.values()) {
+                    await this.closeAndRemove(openFile);
+                }
+                openFiles.clear();
+            },
+        };
+    }
+    async writeQuads(openFiles, dataset, quads) {
         // Peek at the first quad to avoid creating empty files.
         const iterator = quads[Symbol.asyncIterator]();
         const first = await iterator.next();
         if (first.done)
             return;
-        const { n3Writer } = await this.getOrCreateWriter(dataset);
+        const { n3Writer } = await this.getOrCreateFile(openFiles, dataset);
         // Re-emit each quad into the configured named graph (n-quads only). The
         // pipeline's quads carry no graph context, so the graph is supplied here
         // exactly as SparqlUpdateWriter supplies it via INSERT DATA { GRAPH … }.
@@ -52,23 +76,25 @@ export class FileWriter {
             addQuad(quad);
         }
     }
-    async flush(dataset) {
-        const key = this.getFilePath(dataset);
-        const entry = this.activeWriters.get(key);
-        if (!entry)
+    async flushFile(openFiles, dataset) {
+        await this.flushPath(openFiles, this.getFilePath(dataset));
+    }
+    async flushPath(openFiles, finalPath) {
+        const openFile = openFiles.get(finalPath);
+        if (!openFile)
             return;
-        this.activeWriters.delete(key);
+        openFiles.delete(finalPath);
         // Quads are streamed to a sibling temp file; only on a clean flush is it
         // atomically renamed onto the final path. A crash therefore leaves at most
         // a stale `*.tmp` — never a truncated final file — so a downstream index
         // rebuild that globs the final extension never reads a half-written file.
         try {
             await new Promise((resolve, reject) => {
-                if (entry.stream.errored) {
-                    reject(entry.stream.errored);
+                if (openFile.stream.errored) {
+                    reject(openFile.stream.errored);
                     return;
                 }
-                entry.n3Writer.end((error) => {
+                openFile.n3Writer.end((error) => {
                     if (error)
                         reject(error);
                     else
@@ -77,26 +103,32 @@ export class FileWriter {
             });
         }
         catch (error) {
-            await rm(entry.tempPath, { force: true, recursive: true });
+            await rm(openFile.tempPath, { force: true, recursive: true });
             throw error;
         }
-        await rename(entry.tempPath, key);
+        await rename(openFile.tempPath, finalPath);
     }
-    async reset(dataset) {
+    async discardFile(openFiles, dataset) {
         const key = this.getFilePath(dataset);
-        const entry = this.activeWriters.get(key);
-        if (!entry)
+        const openFile = openFiles.get(key);
+        if (!openFile)
             return;
         // Drop the open writer and remove its temp file so the next write starts a
-        // fresh file, discarding everything streamed during the previous pass. Await
-        // the stream closing before removing: the write stream opens its fd lazily,
-        // so a pending open could otherwise recreate the file after rm() ran.
-        this.activeWriters.delete(key);
+        // fresh file, discarding everything streamed during the previous pass.
+        openFiles.delete(key);
+        await this.closeAndRemove(openFile);
+    }
+    /**
+     * Close an open file's stream and remove its temp file. Await the stream
+     * closing before removing: the write stream opens its fd lazily, so a
+     * pending open could otherwise recreate the file after rm() ran.
+     */
+    async closeAndRemove(openFile) {
         await new Promise((resolve) => {
-            entry.stream.once('close', resolve);
-            entry.stream.destroy();
+            openFile.stream.once('close', resolve);
+            openFile.stream.destroy();
         });
-        await rm(entry.tempPath, { force: true, recursive: true });
+        await rm(openFile.tempPath, { force: true, recursive: true });
     }
     getOutputPath(dataset) {
         return this.getFilePath(dataset);
@@ -111,16 +143,16 @@ export class FileWriter {
     getFilePath(dataset) {
         return join(this.outputDir, this.getFilename(dataset));
     }
-    async getOrCreateWriter(dataset) {
-        const key = this.getFilePath(dataset);
-        const existing = this.activeWriters.get(key);
+    async getOrCreateFile(openFiles, dataset) {
+        const finalPath = this.getFilePath(dataset);
+        const existing = openFiles.get(finalPath);
         if (existing)
             return existing;
-        await mkdir(dirname(key), { recursive: true });
+        await mkdir(dirname(finalPath), { recursive: true });
         // Write to a sibling temp file (same directory, so the flush rename stays on
         // one filesystem and is atomic). The `.tmp` suffix keeps it out of any glob
         // on the final extension.
-        const tempPath = `${key}.tmp`;
+        const tempPath = `${finalPath}.tmp`;
         const stream = createWriteStream(tempPath, { flags: 'w' });
         stream.on('error', (error) => {
             // Surface stream errors when flushing; prevents 'unhandled error' crashes.
@@ -130,9 +162,9 @@ export class FileWriter {
             format: formatMap[this.format],
             prefixes: this.prefixes,
         });
-        const entry = { n3Writer, stream, tempPath };
-        this.activeWriters.set(key, entry);
-        return entry;
+        const openFile = { n3Writer, stream, tempPath, finalPath };
+        openFiles.set(finalPath, openFile);
+        return openFile;
     }
     getExtension() {
         switch (this.format) {

package/dist/writer/sparqlUpdateWriter.d.ts

@@ -1,6 +1,5 @@
 import { Dataset } from '@lde/dataset';
-import type { Quad } from '@rdfjs/types';
-import { Writer } from './writer.js';
+import { RunContext, RunWriter, Writer } from './writer.js';
 export interface SparqlWriterOptions {
     /**
      * The SPARQL UPDATE endpoint URL.
@@ -34,12 +33,25 @@ export interface SparqlWriterOptions {
      */
     graphIri?: (dataset: Dataset) => URL;
 }
+/**
+ * The run writer a {@link SparqlUpdateWriter} opens: per-dataset `reset` is
+ * always available, so direct callers need no optional chaining.
+ */
+export interface SparqlUpdateRunWriter extends RunWriter {
+    reset(dataset: Dataset): Promise<void>;
+}
 /**
  * Writes RDF data to a SPARQL endpoint using SPARQL UPDATE INSERT DATA queries.
  *
- * Clears the named graph before the first write per dataset per instance, then
- * streams quads in batches to avoid accumulating the entire dataset in memory.
- * Subsequent calls to {@link write} for the same dataset append rather than replace.
+ * Within a run ({@link openRun}), the named graph is cleared before the first
+ * write per dataset, then quads are streamed in batches to avoid accumulating
+ * the entire dataset in memory. Subsequent writes for the same dataset within
+ * the run append rather than replace. Each new run starts with fresh
+ * cleared-graph state, so re-running a pipeline replaces each graph again.
+ *
+ * The writes are visible as they land (no run-level staging), so `commit` and
+ * `abort` are no-ops: an aborted run leaves the graphs written so far, to be
+ * replaced by the next run.
  */
 export declare class SparqlUpdateWriter implements Writer {
     private readonly endpoint;
@@ -47,10 +59,9 @@ export declare class SparqlUpdateWriter implements Writer {
     private readonly fetch;
     private readonly batchSize;
     private readonly graphIri;
-    private readonly clearedGraphs;
     constructor(options: SparqlWriterOptions);
-    write(dataset: Dataset, quads: AsyncIterable<Quad>): Promise<void>;
-    reset(dataset: Dataset): Promise<void>;
+    openRun(_context?: RunContext): Promise<SparqlUpdateRunWriter>;
+    private writeQuads;
     private clearGraph;
     private insertBatch;
     private executeUpdate;

package/dist/writer/sparqlUpdateWriter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sparqlUpdateWriter.d.ts","sourceRoot":"","sources":["../../src/writer/sparqlUpdateWriter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAiB,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,GAAG,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,MAAM;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,OAAO,EAAE,mBAAmB;IAQlC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;YAM9B,UAAU;YAIV,WAAW;YAOX,aAAa;CAuB5B"}
+{"version":3,"file":"sparqlUpdateWriter.d.ts","sourceRoot":"","sources":["../../src/writer/sparqlUpdateWriter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAiB,MAAM,cAAc,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG5D,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,GAAG,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,SAAS;IACtD,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,YAAW,MAAM;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;gBAEzC,OAAO,EAAE,mBAAmB;IAQlC,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC;YActD,UAAU;YAkBV,UAAU;YAIV,WAAW;YAOX,aAAa;CAuB5B"}

package/dist/writer/sparqlUpdateWriter.js

@@ -4,9 +4,15 @@ import { serializeQuads } from './serialize.js';
 /**
  * Writes RDF data to a SPARQL endpoint using SPARQL UPDATE INSERT DATA queries.
  *
- * Clears the named graph before the first write per dataset per instance, then
- * streams quads in batches to avoid accumulating the entire dataset in memory.
- * Subsequent calls to {@link write} for the same dataset append rather than replace.
+ * Within a run ({@link openRun}), the named graph is cleared before the first
+ * write per dataset, then quads are streamed in batches to avoid accumulating
+ * the entire dataset in memory. Subsequent writes for the same dataset within
+ * the run append rather than replace. Each new run starts with fresh
+ * cleared-graph state, so re-running a pipeline replaces each graph again.
+ *
+ * The writes are visible as they land (no run-level staging), so `commit` and
+ * `abort` are no-ops: an aborted run leaves the graphs written so far, to be
+ * replaced by the next run.
  */
 export class SparqlUpdateWriter {
     endpoint;
@@ -14,7 +20,6 @@ export class SparqlUpdateWriter {
     fetch;
     batchSize;
     graphIri;
-    clearedGraphs = new Set();
     constructor(options) {
         this.endpoint = options.endpoint;
         this.auth = options.auth;
@@ -22,22 +27,30 @@ export class SparqlUpdateWriter {
         this.batchSize = options.batchSize ?? 10000;
         this.graphIri = options.graphIri ?? ((dataset) => dataset.iri);
     }
-    async write(dataset, quads) {
+    async openRun(_context) {
+        const clearedGraphs = new Set();
+        return {
+            write: (dataset, quads) => this.writeQuads(clearedGraphs, dataset, quads),
+            reset: async (dataset) => {
+                // Forget the graph’s cleared state so the next write re-issues
+                // CLEAR GRAPH, replacing the prior output instead of appending to it.
+                clearedGraphs.delete(this.graphIri(dataset).toString());
+            },
+            commit: () => Promise.resolve(),
+            abort: () => Promise.resolve(),
+        };
+    }
+    async writeQuads(clearedGraphs, dataset, quads) {
         const graphUri = this.graphIri(dataset).toString();
         assertSafeIri(graphUri);
-        if (!this.clearedGraphs.has(graphUri)) {
+        if (!clearedGraphs.has(graphUri)) {
             await this.clearGraph(graphUri);
-            this.clearedGraphs.add(graphUri);
+            clearedGraphs.add(graphUri);
         }
         for await (const chunk of batch(quads, this.batchSize)) {
             await this.insertBatch(graphUri, chunk);
         }
     }
-    async reset(dataset) {
-        // Forget the graph’s cleared state so the next write re-issues CLEAR GRAPH,
-        // replacing the prior output instead of appending to it.
-        this.clearedGraphs.delete(this.graphIri(dataset).toString());
-    }
     async clearGraph(graphUri) {
         await this.executeUpdate(`CLEAR GRAPH <${graphUri}>`);
     }

package/dist/writer/writer.d.ts

@@ -1,35 +1,113 @@
 import { Dataset } from '@lde/dataset';
 import type { Quad } from '@rdfjs/types';
+import type { ProvenanceStore } from '../provenance/store.js';
 /**
- * Interface for writing RDF data to a destination.
+ * Context for one pipeline run, handed to {@link Writer.openRun}.
  */
-export interface Writer {
+export interface RunContext {
     /**
-     * Write RDF data for a dataset to the destination.
+     * Unique identifier of this run. An In-place writer stamps written documents
+     * with it so its commit sweep can delete what the run did not touch; a
+     * Blue/green writer may use it to name the fresh collection it builds.
+     */
+    readonly runId: string;
+    /**
+     * ISO 8601 timestamp taken when the run opened. Injected so writers need no
+     * clock of their own.
+     */
+    readonly startedAt: string;
+    /**
+     * IRIs of every dataset the selector produced this run – including datasets
+     * the pipeline skipped as unchanged. Grows while the pipeline iterates the
+     * selection; it is complete by the time {@link RunWriter.commit} runs, which
+     * is when a registry-membership sweep should read it.
+     */
+    selectedSources(): Iterable<string>;
+    /**
+     * The pipeline’s per-dataset processing memory, present when skip-unchanged
+     * is enabled ({@link PipelineOptions.provenanceStore}).
+     */
+    readonly provenance?: ProvenanceStore;
+}
+/**
+ * The per-dataset write surface of a {@link RunWriter}: what a stage writes
+ * its output through. Separate from the run lifecycle so stages can write but
+ * never commit or abort the run.
+ */
+export interface DatasetWriter<Item = Quad> {
+    /**
+     * Write a dataset’s items to the destination. Called one or more times per
+     * dataset (once per stage) within an open run.
      *
      * @param dataset The dataset metadata
-     * @param quads The RDF quads to write
+     * @param items The items to write
      */
-    write(dataset: Dataset, quads: AsyncIterable<Quad>): Promise<void>;
+    write(dataset: Dataset, items: AsyncIterable<Item>): Promise<void>;
+}
+/**
+ * One open run transaction on a destination: per-dataset writes bracketed by
+ * exactly one {@link commit} or {@link abort}. Obtained from
+ * {@link Writer.openRun}; the pipeline drives
+ * `openRun → write* → commit/abort` uniformly and never branches on the
+ * writer’s update mode – an atomic swap or a deletion sweep is the writer’s
+ * own business, inside {@link commit}.
+ */
+export interface RunWriter<Item = Quad> extends DatasetWriter<Item> {
     /**
-     * Finalize writing for a dataset. Called after all stages complete.
+     * Finalize writing for a dataset. Called after all stages complete for that
+     * dataset.
      *
      * Writers that buffer output across multiple {@link write} calls (e.g. to
      * share Turtle prefix declarations) should implement this to flush remaining
-     * data and release resources.
+     * data and release per-dataset resources.
      */
     flush?(dataset: Dataset): Promise<void>;
     /**
-     * Discard a dataset’s already-written output so a subsequent run starts from
-     * a clean slate. Called by the pipeline before it re-runs all stages against
-     * a fallback source (an imported data dump), so endpoint-sourced partial
-     * results are not mixed with the dump-sourced re-run.
+     * Discard a dataset’s already-written output so a subsequent pass starts
+     * from a clean slate. Called by the pipeline before it re-runs all stages
+     * against a fallback source (an imported data dump), so endpoint-sourced
+     * partial results are not mixed with the dump-sourced re-run.
      *
-     * Writers that build a complete replacement per dataset (e.g.
-     * {@link SparqlUpdateWriter}, which clears each graph on first write) should
-     * implement this to reset that per-dataset state. Writers without
-     * replaceable output may omit it; the re-run then appends.
+     * Writers that build a complete replacement per dataset should implement
+     * this to reset that per-dataset state. Writers without replaceable output
+     * may omit it; the re-run then appends.
      */
     reset?(dataset: Dataset): Promise<void>;
+    /**
+     * Finalize the run: the one place a destination goes live. A Blue/green
+     * writer atomically swaps its alias to the freshly built collection; an
+     * In-place writer sweeps documents the run did not touch and releases its
+     * lock. Called exactly once, after every dataset has been processed.
+     *
+     * The driver flushes every written dataset before committing (the Pipeline
+     * does), so unflushed writes only reach `commit` under direct use; a writer
+     * that can encounter them should finalize them non-destructively.
+     */
+    commit(): Promise<void>;
+    /**
+     * Abandon the run after a failure: the live destination must be left as it
+     * was before the run. A Blue/green writer drops its half-built collection;
+     * an In-place writer releases its lock and lets the next run reconcile.
+     *
+     * @param error The failure that ended the run
+     */
+    abort(error: unknown): Promise<void>;
+}
+/**
+ * A destination for pipeline output: a factory of per-run transactions.
+ *
+ * Each pipeline run opens one {@link RunWriter} via {@link openRun} – the
+ * home of run-level lifecycle such as alias swaps, deletion sweeps and
+ * cross-pod locks. A destination without run-level state simply returns its
+ * per-dataset writes with no-op `commit`/`abort` (see
+ * {@link SparqlUpdateWriter} for the pattern).
+ */
+export interface Writer<Item = Quad> {
+    /**
+     * Open a run transaction against this destination.
+     *
+     * @param context The run’s identity and selection scope
+     */
+    openRun(context: RunContext): Promise<RunWriter<Item>>;
 }
 //# sourceMappingURL=writer.d.ts.map

package/dist/writer/writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/writer/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC"}
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/writer/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,IAAI;IACxC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,IAAI,GAAG,IAAI,CAAE,SAAQ,aAAa,CAAC,IAAI,CAAC;IACjE;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;OASG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,GAAG,IAAI;IACjC;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;CACxD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.31.5",
+  "version": "0.32.0",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/pipeline"
@@ -24,12 +24,12 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/dataset": "^0.7.7",
-    "@lde/dataset-registry-client": "^0.8.4",
-    "@lde/distribution-health": "^0.2.2",
-    "@lde/distribution-probe": "^0.2.2",
-    "@lde/sparql-importer": "^0.6.5",
-    "@lde/sparql-server": "^0.4.11",
+    "@lde/dataset": "^0.7.8",
+    "@lde/dataset-registry-client": "^0.8.5",
+    "@lde/distribution-health": "^0.2.3",
+    "@lde/distribution-probe": "^0.2.3",
+    "@lde/sparql-importer": "^0.6.6",
+    "@lde/sparql-server": "^0.4.12",
     "@rdfjs/namespace": "^2.0.1",
     "@rdfjs/types": "^2.0.1",
     "@tpluscode/rdf-ns-builders": "^5.0.0",

package/dist/sparql/executor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/sparql/executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAiB,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUxC,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAS5B;;GAEG;AACH,qBAAa,YAAY;aACK,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAC5C;AAED,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAE9B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CACL,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,uBAAwB,YAAW,QAAQ;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwB;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,OAAO,EAAE,8BAA8B;IAiBnD;;;;;;;OAOG;IACG,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IA4C/B;;;;;OAKG;YACW,oBAAoB;IA+BlC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;OAIG;YACW,UAAU;IAmBxB;;;;;OAKG;WACiB,QAAQ,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,8BAA8B,EAAE,OAAO,CAAC,GACtD,OAAO,CAAC,uBAAuB,CAAC;CAIpC;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,OAAO,CAAC,SAAS,CAAM;IAEd,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI;IAUjE,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI;CAMrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,gBAAgB,CACrC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GACzB,aAAa,CAAC,IAAI,CAAC,CASrB"}