@lde/pipeline 0.30.1 → 0.30.3

package/README.md

@@ -208,6 +208,44 @@ new Stage({
 
 This keeps SPARQL doing the heavy lifting while TypeScript handles the edge cases. See [@lde/pipeline-void](../pipeline-void)'s `VocabularyExecutor` for a real-world example of this pattern.
 
+#### Adaptive timeouts
+
+By default, every SPARQL request uses the same 5-minute budget. When a pipeline runs against many third-party endpoints, that fixed budget can cost ~80 minutes on a single dataset whose endpoint times out repeatedly on heavy queries — light stages on the same endpoint then sit behind the heavy ones that will never succeed.
+
+A `TimeoutPolicy` decides the budget for each SPARQL request and observes the outcome. Two are built in:
+
+- **`ConstantTimeoutPolicy(timeoutMs)`** – returns the same budget for every request. The implicit default when `PipelineOptions.timeout` is omitted (`constantTimeoutPolicy(300_000)`).
+- **`AdaptiveTimeoutPolicy({ defaultMs, tightenedMs, tightenAfterTimeouts })`** – per-endpoint state machine. Each endpoint is either _healthy_ (use `defaultMs`) or _tightened_ (use `tightenedMs`). After `tightenAfterTimeouts` consecutive `timeout` outcomes the endpoint flips to _tightened_; a single `ok` flips it back to _healthy_.
+
+`PipelineOptions.timeout` accepts a `() => TimeoutPolicy` factory. The pipeline invokes it once per dataset, so policy state resets between datasets and one bad dataset can’t poison the next:
+
+```typescript
+import { adaptiveTimeoutPolicy } from '@lde/pipeline';
+
+new Pipeline({
+  // …
+  timeout: adaptiveTimeoutPolicy({
+    defaultMs: 300_000, //         5 min while the endpoint is healthy
+    tightenedMs: 10_000, //        10 s once the endpoint is tightened
+    tightenAfterTimeouts: 2, //    flip to tightened after 2 consecutive timeouts
+  }),
+});
+```
+
+Outcomes are classified as:
+
+| outcome   | source                                                                   |
+| --------- | ------------------------------------------------------------------------ |
+| `ok`      | the request resolved                                                     |
+| `timeout` | client-side `AbortSignal.timeout()` fired, or upstream returned HTTP 504 |
+| `error`   | anything else (other HTTP errors, parse errors, …) – neutral             |
+
+Transitions are forwarded to the `ProgressReporter` via `timeoutTightened` / `timeoutRelaxed`; `ConsoleReporter` prints them as `↘ Tightened` / `↗ Relaxed` lines so operators can tell a fast-failed stage from an unexpected speedup.
+
+Implement `TimeoutPolicy` directly for custom strategies (closing over shared state in the factory if you want it to span datasets).
+
+Timeouts live at the pipeline level — neither `SparqlConstructExecutor` nor `SparqlItemSelector` accept their own `timeout` option. Per-endpoint state belongs in the adaptive policy, and per-stage budgets aren’t supported. Reusable stage facades (`@lde/pipeline-void`, `@lde/pipeline-shacl-sampler`) follow the same convention.
+
 ### Validation
 
 Stages can optionally validate their output quads against a `Validator`. Validation operates on the **combined output of all executors per batch**, not on individual quads or per-executor output. A batch produces a complete result set — a self-contained cluster of linked resources — that can be meaningfully matched against SHACL shapes. Even with a single executor, each batch is a complete unit; with multiple executors, shapes that reference triples from different executors are validated correctly.

package/dist/pipeline.d.ts

@@ -5,6 +5,7 @@ import type { Writer } from './writer/writer.js';
 import { type DistributionResolver } from './distribution/resolver.js';
 import type { StageOutputResolver } from './stageOutputResolver.js';
 import type { ProgressReporter } from './progressReporter.js';
+import { type TimeoutPolicy } from './sparql/timeoutPolicy.js';
 /** Plugin that hooks into pipeline lifecycle events. */
 export interface PipelinePlugin {
     name: string;
@@ -23,6 +24,17 @@ export interface PipelineOptions {
         outputDir: string;
     };
     reporter?: ProgressReporter;
+    /**
+     * Factory producing a fresh {@link TimeoutPolicy} per dataset. Defaults
+     * to {@link constantTimeoutPolicy}`(300_000)` so existing call sites
+     * keep today’s 5-minute fixed budget.
+     *
+     * Use {@link adaptiveTimeoutPolicy} to fast-fail stages on endpoints
+     * that have shown a run of consecutive timeouts. State is per
+     * {@link TimeoutPolicy} instance, and the Pipeline invokes the factory
+     * once per dataset so state resets between datasets.
+     */
+    timeout?: () => TimeoutPolicy;
 }
 export declare class Pipeline {
     private readonly name;
@@ -32,6 +44,7 @@ export declare class Pipeline {
     private readonly distributionResolver;
     private readonly chaining?;
     private readonly reporter?;
+    private readonly timeoutFactory;
     constructor(options: PipelineOptions);
     run(): Promise<void>;
     private processDataset;

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,aAAa,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,eAAe,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,EAAE;QACT,mBAAmB,EAAE,mBAAmB,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAgFD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmB;gBAEjC,OAAO,EAAE,eAAe;IAgC9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAoBZ,cAAc;YAmEd,gBAAgB;IAW9B,OAAO,CAAE,aAAa;IAOtB;;;OAGG;YACW,QAAQ;IAwCtB,2EAA2E;YAC7D,eAAe;YAcf,QAAQ;YAmDP,SAAS;CAczB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAEnC,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,aAAa,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,eAAe,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,EAAE;QACT,mBAAmB,EAAE,mBAAmB,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,aAAa,CAAC;CAC/B;AAgFD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;gBAEzC,OAAO,EAAE,eAAe;IAkC9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAoBZ,cAAc;YAgFd,gBAAgB;IAW9B,OAAO,CAAE,aAAa;IAOtB;;;OAGG;YACW,QAAQ;IA0CtB,2EAA2E;YAC7D,eAAe;YAqBf,QAAQ;YA2DP,SAAS;CAczB"}

package/dist/pipeline.js

@@ -5,6 +5,7 @@ import { NoDistributionAvailable, } from './distribution/resolver.js';
 import { SparqlDistributionResolver } from './distribution/index.js';
 import { NetworkError, SparqlProbeResult, } from '@lde/distribution-probe';
 import { NotSupported } from './sparql/executor.js';
+import { ConstantTimeoutPolicy, } from './sparql/timeoutPolicy.js';
 /**
  * Split an async iterable into `count` branches that can be consumed
  * independently. Backpressure is enforced by the slowest consumer –
@@ -79,6 +80,7 @@ export class Pipeline {
     distributionResolver;
     chaining;
     reporter;
+    timeoutFactory;
     constructor(options) {
         const hasSubStages = options.stages.some((stage) => stage.stages.length > 0);
         if (hasSubStages && !options.chaining) {
@@ -102,6 +104,8 @@ export class Pipeline {
             options.distributionResolver ?? new SparqlDistributionResolver();
         this.chaining = options.chaining;
         this.reporter = options.reporter;
+        this.timeoutFactory =
+            options.timeout ?? (() => new ConstantTimeoutPolicy(300_000));
     }
     async run() {
         const start = Date.now();
@@ -121,6 +125,11 @@ export class Pipeline {
     }
     async processDataset(dataset) {
         this.reporter?.datasetStart?.(dataset);
+        const timeout = this.timeoutFactory();
+        const unsubscribe = timeout.subscribe?.({
+            onTighten: (event) => this.reporter?.timeoutTightened?.(event),
+            onRelax: (event) => this.reporter?.timeoutRelaxed?.(event),
+        });
         let resolved;
         try {
             resolved = await this.distributionResolver.resolve(dataset, {
@@ -148,10 +157,10 @@ export class Pipeline {
             for (const stage of this.stages) {
                 try {
                     if (stage.stages.length > 0) {
-                        await this.runChain(dataset, resolved.distribution, stage);
+                        await this.runChain(dataset, resolved.distribution, stage, timeout);
                     }
                     else {
-                        await this.runStage(dataset, resolved.distribution, stage);
+                        await this.runStage(dataset, resolved.distribution, stage, this.writer, timeout);
                     }
                 }
                 catch (error) {
@@ -161,6 +170,7 @@ export class Pipeline {
         }
         finally {
             await this.distributionResolver.cleanup?.();
+            unsubscribe?.();
         }
         await this.writer.flush?.(dataset);
         await this.reportValidators(dataset);
@@ -192,7 +202,7 @@ export class Pipeline {
      * Run a stage with reporting and return whether it was supported.
      * Returns `true` if the stage produced results, `false` if NotSupported.
      */
-    async runStage(dataset, distribution, stage, writer = this.writer) {
+    async runStage(dataset, distribution, stage, writer = this.writer, timeout) {
         this.reporter?.stageStart?.(stage.name);
         const stageStart = Date.now();
         let itemsProcessed = 0;
@@ -209,6 +219,7 @@ export class Pipeline {
                     heapUsedBytes: stageMemory.heapUsed,
                 });
             },
+            timeout,
         });
         if (result instanceof NotSupported) {
             this.reporter?.stageSkipped?.(stage.name, result.message);
@@ -222,13 +233,13 @@ export class Pipeline {
         return true;
     }
     /** Run a stage in chained mode, throwing if the stage is not supported. */
-    async runChainedStage(dataset, distribution, stage, writer) {
-        const supported = await this.runStage(dataset, distribution, stage, writer);
+    async runChainedStage(dataset, distribution, stage, writer, timeout) {
+        const supported = await this.runStage(dataset, distribution, stage, writer, timeout);
         if (!supported) {
             throw new Error(`Stage '${stage.name}' returned NotSupported in chained mode`);
         }
     }
-    async runChain(dataset, distribution, stage) {
+    async runChain(dataset, distribution, stage, timeout) {
         const { stageOutputResolver, outputDir } = this.chaining;
         const outputFiles = [];
         try {
@@ -237,7 +248,7 @@ export class Pipeline {
                 outputDir: `${outputDir}/${stage.name}`,
                 format: 'n-triples',
             });
-            await this.runChainedStage(dataset, distribution, stage, parentWriter);
+            await this.runChainedStage(dataset, distribution, stage, parentWriter, timeout);
             outputFiles.push(parentWriter.getOutputPath(dataset));
             // 2. Chain through children.
             let currentDistribution = await stageOutputResolver.resolve(parentWriter.getOutputPath(dataset));
@@ -247,7 +258,7 @@ export class Pipeline {
                     outputDir: `${outputDir}/${child.name}`,
                     format: 'n-triples',
                 });
-                await this.runChainedStage(dataset, currentDistribution, child, childWriter);
+                await this.runChainedStage(dataset, currentDistribution, child, childWriter, timeout);
                 outputFiles.push(childWriter.getOutputPath(dataset));
                 if (i < stage.stages.length - 1) {
                     currentDistribution = await stageOutputResolver.resolve(childWriter.getOutputPath(dataset));

package/dist/progressReporter.d.ts

@@ -1,5 +1,6 @@
 import type { Dataset, Distribution } from '@lde/dataset';
 import type { ValidationReport } from './validator.js';
+import type { TimeoutTransitionEvent } from './sparql/timeoutPolicy.js';
 export interface DistributionAnalysisResult {
     distribution: Distribution;
     type: 'sparql' | 'data-dump' | 'network-error';
@@ -53,5 +54,16 @@ export interface ProgressReporter {
         memoryUsageBytes: number;
         heapUsedBytes: number;
     }): void;
+    /**
+     * Called when a {@link TimeoutPolicy} tightens the budget for an
+     * endpoint after a run of consecutive timeouts. Lets operators
+     * distinguish a fast-failed stage from an unexpected speedup.
+     */
+    timeoutTightened?(event: TimeoutTransitionEvent): void;
+    /**
+     * Called when a {@link TimeoutPolicy} relaxes the budget back to the
+     * default after a successful request on a previously-tightened endpoint.
+     */
+    timeoutRelaxed?(event: TimeoutTransitionEvent): void;
 }
 //# sourceMappingURL=progressReporter.d.ts.map

package/dist/progressReporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progressReporter.d.ts","sourceRoot":"","sources":["../src/progressReporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,8DAA8D;IAC9D,kBAAkB,CAAC,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC9D,6CAA6C;IAC7C,aAAa,CAAC,IAAI,IAAI,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,oBAAoB,CAAC,CACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,cAAc,CAAC,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAAC;IACR,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,aAAa,CAAC,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QACN,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;KAClB,GACA,IAAI,CAAC;IACR,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChD,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,CACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC1D,IAAI,CAAC;IACR,cAAc,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,gBAAgB,CAAC,CAAC,MAAM,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;CACV"}
+{"version":3,"file":"progressReporter.d.ts","sourceRoot":"","sources":["../src/progressReporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,8DAA8D;IAC9D,kBAAkB,CAAC,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC9D,6CAA6C;IAC7C,aAAa,CAAC,IAAI,IAAI,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,oBAAoB,CAAC,CACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,cAAc,CAAC,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAAC;IACR,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,aAAa,CAAC,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QACN,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;KAClB,GACA,IAAI,CAAC;IACR,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChD,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,CACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC1D,IAAI,CAAC;IACR,cAAc,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,gBAAgB,CAAC,CAAC,MAAM,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACvD;;;OAGG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACtD"}

package/dist/sparql/executor.d.ts

@@ -2,6 +2,7 @@ import { Dataset, Distribution } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 import type { NamedNode, Quad } from '@rdfjs/types';
 import { Transform } from 'node:stream';
+import { type TimeoutPolicy } from './timeoutPolicy.js';
 /**
  * An executor could not run because the dataset lacks a supported distribution.
  */
@@ -17,6 +18,16 @@ export interface ExecuteOptions {
      * When non-empty, a VALUES block is prepended to the WHERE clause.
      */
     bindings?: VariableBindings[];
+    /**
+     * Per-call {@link TimeoutPolicy}. When supplied, the executor calls
+     * {@link TimeoutPolicy.beforeRequest} once per attempt (including
+     * retries), installs an {@link AbortSignal} with the returned budget,
+     * and reports the outcome via {@link TimeoutPolicy.afterRequest}.
+     *
+     * Overrides the executor-level policy passed at construction time.
+     * Pipeline runners use this to thread the per-dataset policy through.
+     */
+    timeout?: TimeoutPolicy;
 }
 export interface Executor {
     execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad> | NotSupported>;
@@ -29,11 +40,6 @@ export interface SparqlConstructExecutorOptions {
      * SPARQL CONSTRUCT query to execute.
      */
     query: string;
-    /**
-     * Optional timeout for SPARQL queries in milliseconds.
-     * @default 300000 (5 minutes)
-     */
-    timeout?: number;
     /**
      * Number of retries for transient errors (network failures and HTTP 502/503/504).
      * @default 3
@@ -41,6 +47,20 @@ export interface SparqlConstructExecutorOptions {
     retries?: number;
     /**
      * Optional custom SparqlEndpointFetcher instance.
+     *
+     * When supplied, the executor uses this fetcher as-is for every attempt
+     * — the per-attempt timeout from the {@link TimeoutPolicy} is **not**
+     * enforced (the supplied fetcher’s own `timeout` governs). Policy
+     * `beforeRequest`/`afterRequest` hooks still fire so outcome
+     * classification works, but adaptive tightening cannot apply.
+     *
+     * When omitted, the executor builds a fresh
+     * {@link SparqlEndpointFetcher} per attempt with the per-attempt timeout
+     * baked in.
+     *
+     * This option is intended for tests (mocking `fetchTriples`) and
+     * advanced cases that need full control of the fetcher. Most callers
+     * should leave it unset.
      */
     fetcher?: SparqlEndpointFetcher;
     /**
@@ -101,7 +121,7 @@ export interface SparqlConstructExecutorOptions {
 export declare class SparqlConstructExecutor implements Executor {
     private readonly rawQuery;
     private readonly preParsed?;
-    private readonly fetcher;
+    private readonly userFetcher?;
     private readonly retries;
     private readonly lineBuffer;
     private readonly deduplicate;
@@ -116,6 +136,22 @@ export declare class SparqlConstructExecutor implements Executor {
      * @returns AsyncIterable<Quad> stream of results.
      */
     execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad>>;
+    /**
+     * Run a single attempt against the endpoint with a per-call abort
+     * signal derived from {@link TimeoutPolicy.beforeRequest}. Reports the
+     * outcome via {@link TimeoutPolicy.afterRequest} regardless of whether
+     * the attempt resolved or threw.
+     */
+    private fetchQuadsWithPolicy;
+    /**
+     * Pick the fetcher to use for a single attempt. A user-supplied fetcher
+     * is used as-is and its own timeout governs the request; the per-attempt
+     * policy budget is bypassed in that case (see the JSDoc on
+     * {@link SparqlConstructExecutorOptions.fetcher}). Otherwise a fresh
+     * {@link SparqlEndpointFetcher} is constructed per attempt with the
+     * policy-supplied timeout baked in.
+     */
+    private fetcherForAttempt;
     /**
      * Fetch quads from the endpoint, optionally line-buffering the response
      * stream before it reaches the N3 parser to work around

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

@@ -1 +1 @@
-{"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;AAWxC;;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;CAC/B;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;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;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,OAAO,CAAwB;IAChD,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;IAqBnD;;;;;;;OAOG;IACG,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IA0C/B;;;;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,CACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,IAAI;IAWb,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"}
+{"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"}

package/dist/sparql/executor.js

@@ -11,6 +11,13 @@ import pRetry from 'p-retry';
 import { quadToStringQuad } from 'rdf-string';
 import { withDefaultGraph } from './graph.js';
 import { injectValues } from './values.js';
+import { ConstantTimeoutPolicy, } from './timeoutPolicy.js';
+/**
+ * Fallback policy when no per-call `TimeoutPolicy` is supplied via
+ * {@link ExecuteOptions.timeout}. Pipeline always supplies one, so this only
+ * matters when the executor is driven directly (without a Pipeline).
+ */
+const defaultTimeoutPolicy = new ConstantTimeoutPolicy(300_000);
 /**
  * An executor could not run because the dataset lacks a supported distribution.
  */
@@ -50,7 +57,7 @@ export class NotSupported {
 export class SparqlConstructExecutor {
     rawQuery;
     preParsed;
-    fetcher;
+    userFetcher;
     retries;
     lineBuffer;
     deduplicate;
@@ -67,11 +74,7 @@ export class SparqlConstructExecutor {
             }
             this.preParsed = parsed;
         }
-        this.fetcher =
-            options.fetcher ??
-                new SparqlEndpointFetcher({
-                    timeout: options.timeout ?? 300_000,
-                });
+        this.userFetcher = options.fetcher;
     }
     /**
      * Execute the SPARQL CONSTRUCT query against the distribution's endpoint.
@@ -105,22 +108,65 @@ export class SparqlConstructExecutor {
         let query = this.generator.generate(ast);
         assertSafeIri(dataset.iri.toString());
         query = query.replaceAll('?dataset', `<${dataset.iri}>`);
-        const quads = await pRetry(() => this.fetchQuads(endpoint.toString(), query), {
+        const policy = options?.timeout ?? defaultTimeoutPolicy;
+        const quads = await pRetry(() => this.fetchQuadsWithPolicy(endpoint, query, policy), {
             retries: this.retries,
             shouldRetry: ({ error }) => isTransientError(error),
         });
         return this.deduplicate ? deduplicateQuads(quads) : quads;
     }
+    /**
+     * Run a single attempt against the endpoint with a per-call abort
+     * signal derived from {@link TimeoutPolicy.beforeRequest}. Reports the
+     * outcome via {@link TimeoutPolicy.afterRequest} regardless of whether
+     * the attempt resolved or threw.
+     */
+    async fetchQuadsWithPolicy(endpointUrl, query, policy) {
+        const timeoutMs = policy.beforeRequest({ endpoint: endpointUrl });
+        const fetcher = this.fetcherForAttempt(timeoutMs);
+        const start = Date.now();
+        try {
+            const quads = await this.fetchQuads(fetcher, endpointUrl.toString(), query);
+            policy.afterRequest({
+                endpoint: endpointUrl,
+                outcome: 'ok',
+                durationMs: Date.now() - start,
+            });
+            return quads;
+        }
+        catch (error) {
+            policy.afterRequest({
+                endpoint: endpointUrl,
+                outcome: classifyOutcome(error),
+                durationMs: Date.now() - start,
+                error,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Pick the fetcher to use for a single attempt. A user-supplied fetcher
+     * is used as-is and its own timeout governs the request; the per-attempt
+     * policy budget is bypassed in that case (see the JSDoc on
+     * {@link SparqlConstructExecutorOptions.fetcher}). Otherwise a fresh
+     * {@link SparqlEndpointFetcher} is constructed per attempt with the
+     * policy-supplied timeout baked in.
+     */
+    fetcherForAttempt(timeoutMs) {
+        if (this.userFetcher)
+            return this.userFetcher;
+        return new SparqlEndpointFetcher({ timeout: timeoutMs });
+    }
     /**
      * Fetch quads from the endpoint, optionally line-buffering the response
      * stream before it reaches the N3 parser to work around
      * {@link https://github.com/rdfjs/N3.js/issues/578 | N3.js#578}.
      */
-    async fetchQuads(endpoint, query) {
+    async fetchQuads(fetcher, endpoint, query) {
         if (!this.lineBuffer) {
-            return this.fetcher.fetchTriples(endpoint, query);
+            return fetcher.fetchTriples(endpoint, query);
         }
-        const [contentType, , responseStream] = await this.fetcher.fetchRawStream(endpoint, query, SparqlEndpointFetcher.CONTENTTYPE_TURTLE);
+        const [contentType, , responseStream] = await fetcher.fetchRawStream(endpoint, query, SparqlEndpointFetcher.CONTENTTYPE_TURTLE);
         return responseStream
             .pipe(new LineBufferTransform())
             .pipe(new StreamParser({ format: contentType }));
@@ -219,3 +265,29 @@ function isTransientError(error) {
     const status = Number(match[1]);
     return status === 502 || status === 503 || status === 504;
 }
+/**
+ * Classify a fetch error for {@link TimeoutPolicy} reporting.
+ *
+ * - HTTP 504 → `'timeout'`: the upstream reported it ran out of time. This
+ *   is the exact failure mode adaptive timeouts exist to react to.
+ * - `AbortError` / `TimeoutError`: our own `AbortSignal.timeout()` fired.
+ * - Anything else → `'error'`: neutral with respect to tightening.
+ */
+function classifyOutcome(error) {
+    if (error instanceof Error) {
+        if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+            return 'timeout';
+        }
+        if (error.cause instanceof Error) {
+            if (error.cause.name === 'AbortError' ||
+                error.cause.name === 'TimeoutError') {
+                return 'timeout';
+            }
+        }
+        const match = error.message.match(transientStatusPattern);
+        if (match && Number(match[1]) === 504) {
+            return 'timeout';
+        }
+    }
+    return 'error';
+}

package/dist/sparql/index.d.ts

@@ -2,4 +2,5 @@ export { deduplicateQuads, SparqlConstructExecutor, LineBufferTransform, NotSupp
 export { SparqlItemSelector, type SparqlItemSelectorOptions, } from './selector.js';
 export { injectValues } from './values.js';
 export { withDefaultGraph } from './graph.js';
+export { AdaptiveTimeoutPolicy, ConstantTimeoutPolicy, adaptiveTimeoutPolicy, constantTimeoutPolicy, type AdaptiveTimeoutPolicyOptions, type AfterRequestContext, type BeforeRequestContext, type TimeoutOutcome, type TimeoutPolicy, type TimeoutPolicyObserver, type TimeoutTransitionEvent, } from './timeoutPolicy.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sparql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sparql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC"}

package/dist/sparql/index.js

@@ -2,3 +2,4 @@ export { deduplicateQuads, SparqlConstructExecutor, LineBufferTransform, NotSupp
 export { SparqlItemSelector, } from './selector.js';
 export { injectValues } from './values.js';
 export { withDefaultGraph } from './graph.js';
+export { AdaptiveTimeoutPolicy, ConstantTimeoutPolicy, adaptiveTimeoutPolicy, constantTimeoutPolicy, } from './timeoutPolicy.js';

package/dist/sparql/selector.d.ts

@@ -1,6 +1,6 @@
 import type { Distribution } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
-import type { ItemSelector } from '../stage.js';
+import type { ItemSelector, SelectOptions } from '../stage.js';
 import type { VariableBindings } from './executor.js';
 export interface SparqlItemSelectorOptions {
     /**
@@ -46,8 +46,14 @@ export declare class SparqlItemSelector implements ItemSelector {
     private readonly parsed;
     private readonly queryLimit?;
     private readonly maxResults?;
-    private readonly fetcher;
+    private readonly userFetcher?;
     constructor(options: SparqlItemSelectorOptions);
-    select(distribution: Distribution, batchSize?: number): AsyncIterableIterator<VariableBindings>;
+    select(distribution: Distribution, batchSize?: number, options?: SelectOptions): AsyncIterableIterator<VariableBindings>;
+    /**
+     * Run a single SPARQL request against the endpoint, threading the
+     * per-call timeout from {@link TimeoutPolicy.beforeRequest} and
+     * reporting the outcome to {@link TimeoutPolicy.afterRequest}.
+     */
+    private fetchBindingsWithPolicy;
 }
 //# sourceMappingURL=selector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMtD,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,EAAE,yBAAyB;IAmBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,qBAAqB,CAAC,gBAAgB,CAAC;CAyD3C"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoBtD,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwB;gBAEzC,OAAO,EAAE,yBAAyB;IAmBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CAAC,gBAAgB,CAAC;IA4D1C;;;;OAIG;YACW,uBAAuB;CA8BtC"}

package/dist/sparql/selector.js

@@ -2,6 +2,14 @@ import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 import { Parser } from '@traqula/parser-sparql-1-1';
 import { Generator } from '@traqula/generator-sparql-1-1';
 import { AstFactory, } from '@traqula/rules-sparql-1-1';
+import { ConstantTimeoutPolicy, } from './timeoutPolicy.js';
+const transientStatusPattern = /HTTP status (\d+)/;
+/**
+ * Fallback policy when no per-call `TimeoutPolicy` is supplied via
+ * {@link SelectOptions.timeout}. Pipeline always supplies one, so this only
+ * matters when the selector is driven directly (without a Pipeline).
+ */
+const defaultTimeoutPolicy = new ConstantTimeoutPolicy(300_000);
 const parser = new Parser();
 const generator = new Generator();
 const F = new AstFactory();
@@ -27,7 +35,7 @@ export class SparqlItemSelector {
     parsed;
     queryLimit;
     maxResults;
-    fetcher;
+    userFetcher;
     constructor(options) {
         const parsed = parser.parse(options.query);
         if (parsed.type !== 'query' || parsed.subType !== 'select') {
@@ -40,13 +48,14 @@ export class SparqlItemSelector {
         this.parsed = parsed;
         this.queryLimit = this.parsed.solutionModifiers.limitOffset?.limit;
         this.maxResults = options.maxResults;
-        this.fetcher = options.fetcher ?? new SparqlEndpointFetcher();
+        this.userFetcher = options.fetcher;
     }
-    async *select(distribution, batchSize) {
+    async *select(distribution, batchSize, options) {
         if (this.maxResults === 0)
             return;
         const basePageSize = this.queryLimit ?? batchSize ?? 10;
         const endpoint = distribution.accessUrl;
+        const policy = options?.timeout ?? defaultTimeoutPolicy;
         let offset = 0;
         let totalYielded = 0;
         while (true) {
@@ -59,7 +68,7 @@ export class SparqlItemSelector {
             const effectivePageSize = offset === 0 ? basePageSize : Math.min(basePageSize, remaining);
             this.parsed.solutionModifiers.limitOffset = F.solutionModifierLimitOffset(effectivePageSize, offset, F.gen());
             const paginatedQuery = generator.generate(this.parsed);
-            const stream = (await this.fetcher.fetchBindings(endpoint.toString(), paginatedQuery));
+            const stream = await this.fetchBindingsWithPolicy(endpoint, paginatedQuery, policy);
             let count = 0;
             for await (const record of stream) {
                 const row = Object.fromEntries(Object.entries(record).filter(([, term]) => term.termType === 'NamedNode'));
@@ -79,6 +88,52 @@ export class SparqlItemSelector {
             offset += count;
         }
     }
+    /**
+     * Run a single SPARQL request against the endpoint, threading the
+     * per-call timeout from {@link TimeoutPolicy.beforeRequest} and
+     * reporting the outcome to {@link TimeoutPolicy.afterRequest}.
+     */
+    async fetchBindingsWithPolicy(endpoint, paginatedQuery, policy) {
+        const timeoutMs = policy.beforeRequest({ endpoint });
+        const fetcher = this.userFetcher ?? new SparqlEndpointFetcher({ timeout: timeoutMs });
+        const start = Date.now();
+        try {
+            const stream = (await fetcher.fetchBindings(endpoint.toString(), paginatedQuery));
+            policy.afterRequest({
+                endpoint,
+                outcome: 'ok',
+                durationMs: Date.now() - start,
+            });
+            return stream;
+        }
+        catch (error) {
+            policy.afterRequest({
+                endpoint,
+                outcome: classifyOutcome(error),
+                durationMs: Date.now() - start,
+                error,
+            });
+            throw error;
+        }
+    }
+}
+function classifyOutcome(error) {
+    if (error instanceof Error) {
+        if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+            return 'timeout';
+        }
+        if (error.cause instanceof Error) {
+            if (error.cause.name === 'AbortError' ||
+                error.cause.name === 'TimeoutError') {
+                return 'timeout';
+            }
+        }
+        const match = error.message.match(transientStatusPattern);
+        if (match && Number(match[1]) === 504) {
+            return 'timeout';
+        }
+    }
+    return 'error';
 }
 function isVariableTerm(v) {
     return ('type' in v &&

package/dist/sparql/timeoutPolicy.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Outcome of a single SPARQL request attempt, as reported back to a
+ * {@link TimeoutPolicy} so it can adapt the budget for subsequent requests.
+ *
+ * - `ok` — the request resolved successfully (the HTTP response was accepted
+ *   and the body started streaming).
+ * - `timeout` — the per-call {@link AbortSignal} fired, or the endpoint
+ *   returned an HTTP 504 (upstream-reported timeout). Both are semantically
+ *   ‘the endpoint did not deliver in time’.
+ * - `error` — any other failure (4xx other than 504, parser errors, etc.).
+ *   Neutral with respect to adaptive tightening.
+ */
+export type TimeoutOutcome = 'ok' | 'error' | 'timeout';
+/** Context passed to {@link TimeoutPolicy.beforeRequest}. */
+export interface BeforeRequestContext {
+    /** Endpoint URL the upcoming request will be sent to. */
+    endpoint: URL;
+}
+/** Context passed to {@link TimeoutPolicy.afterRequest}. */
+export interface AfterRequestContext {
+    /** Endpoint URL the request was sent to. */
+    endpoint: URL;
+    /** Classified outcome of the request. */
+    outcome: TimeoutOutcome;
+    /** Wall-clock duration of the request attempt, in milliseconds. */
+    durationMs: number;
+    /** The raw error, when {@link outcome} is `'error'` or `'timeout'`. */
+    error?: unknown;
+}
+/**
+ * Decides the timeout budget for each SPARQL request and observes the
+ * outcome. Implementations are free to adapt the budget based on recent
+ * behaviour — see {@link AdaptiveTimeoutPolicy} for the built-in adaptive
+ * implementation, and {@link ConstantTimeoutPolicy} for fixed-budget
+ * behaviour.
+ *
+ * Hooks are synchronous because they sit on the request hot path; async
+ * work is not supported.
+ */
+export interface TimeoutPolicy {
+    /**
+     * Returns the timeout (in milliseconds) to apply to the upcoming request.
+     * Called once per attempt — including retried attempts inside
+     * {@link p-retry}, so a retry can already use a tightened budget.
+     */
+    beforeRequest(context: BeforeRequestContext): number;
+    /**
+     * Reports the outcome of the request that {@link beforeRequest} budgeted.
+     * Called once per attempt, regardless of outcome.
+     */
+    afterRequest(context: AfterRequestContext): void;
+    /**
+     * Optional observer subscription for state transitions. Returns an
+     * `unsubscribe` function. Policies that don’t transition (e.g. constant)
+     * may omit this hook.
+     */
+    subscribe?(observer: TimeoutPolicyObserver): () => void;
+}
+/** A single tighten/relax transition for one endpoint. */
+export interface TimeoutTransitionEvent {
+    /** Endpoint whose timeout budget changed. */
+    endpoint: URL;
+    /** Budget in effect before the transition. */
+    fromTimeoutMs: number;
+    /** Budget in effect after the transition. */
+    toTimeoutMs: number;
+    /**
+     * Number of consecutive timeouts observed at the moment of the
+     * transition. For a `relax` event, this is the run that ended in the
+     * `ok` that triggered relaxation.
+     */
+    consecutiveTimeouts: number;
+}
+/**
+ * Observer that receives notifications when a policy tightens or relaxes
+ * its budget for an endpoint. Both hooks are optional.
+ */
+export interface TimeoutPolicyObserver {
+    /** Called when the policy flips an endpoint to the tightened budget. */
+    onTighten?(event: TimeoutTransitionEvent): void;
+    /** Called when the policy relaxes an endpoint back to the default budget. */
+    onRelax?(event: TimeoutTransitionEvent): void;
+}
+/**
+ * Returns the same timeout for every request. Use this as the
+ * backwards-compatible default for callers that don’t want adaptive
+ * behaviour.
+ */
+export declare class ConstantTimeoutPolicy implements TimeoutPolicy {
+    private readonly timeoutMs;
+    constructor(timeoutMs: number);
+    beforeRequest(_context: BeforeRequestContext): number;
+    afterRequest(_context: AfterRequestContext): void;
+}
+/** Options for {@link AdaptiveTimeoutPolicy}. */
+export interface AdaptiveTimeoutPolicyOptions {
+    /** Budget applied while the endpoint is healthy. Must be positive. */
+    defaultMs: number;
+    /**
+     * Budget applied after {@link tightenAfterTimeouts} consecutive timeouts.
+     * Must satisfy `tightenedMs < defaultMs`.
+     */
+    tightenedMs: number;
+    /**
+     * Number of consecutive timeouts that flips an endpoint to the
+     * {@link tightenedMs} budget. Must be an integer ≥ 1.
+     */
+    tightenAfterTimeouts: number;
+}
+/**
+ * Adaptive per-endpoint policy: after {@link AdaptiveTimeoutPolicyOptions.tightenAfterTimeouts}
+ * consecutive timeouts on the same endpoint, subsequent requests use the
+ * tightened budget so the pipeline fast-fails instead of waiting out the
+ * full default budget. A single successful request relaxes the endpoint
+ * back to the default budget.
+ *
+ * State is in-memory and tied to the policy instance — Pipeline creates a
+ * fresh instance per dataset so one offending dataset doesn’t poison the
+ * next.
+ *
+ * @example
+ * ```ts
+ * const factory = adaptiveTimeoutPolicy({
+ *   defaultMs: 300_000,
+ *   tightenedMs: 10_000,
+ *   tightenAfterTimeouts: 2,
+ * });
+ * ```
+ */
+export declare class AdaptiveTimeoutPolicy implements TimeoutPolicy {
+    private readonly options;
+    private readonly states;
+    private readonly observers;
+    constructor(options: AdaptiveTimeoutPolicyOptions);
+    beforeRequest(context: BeforeRequestContext): number;
+    afterRequest(context: AfterRequestContext): void;
+    subscribe(observer: TimeoutPolicyObserver): () => void;
+    private stateFor;
+    private notify;
+}
+/**
+ * Factory returning a fresh {@link ConstantTimeoutPolicy} on every call.
+ * Pass this to {@link PipelineOptions.timeout}.
+ */
+export declare function constantTimeoutPolicy(timeoutMs: number): () => ConstantTimeoutPolicy;
+/**
+ * Factory returning a fresh {@link AdaptiveTimeoutPolicy} on every call.
+ * Pass this to {@link PipelineOptions.timeout}; the Pipeline invokes
+ * the factory once per dataset so state resets between datasets.
+ */
+export declare function adaptiveTimeoutPolicy(options: AdaptiveTimeoutPolicyOptions): () => AdaptiveTimeoutPolicy;
+//# sourceMappingURL=timeoutPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeoutPolicy.d.ts","sourceRoot":"","sources":["../../src/sparql/timeoutPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,EAAE,GAAG,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,QAAQ,EAAE,GAAG,CAAC;IACd,yCAAyC;IACzC,OAAO,EAAE,cAAc,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAAC;IACrD;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI,CAAC;CACzD;AAED,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,QAAQ,EAAE,GAAG,CAAC;IACd,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,SAAS,CAAC,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,6EAA6E;IAC7E,OAAO,CAAC,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC/C;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM;IAQ9C,aAAa,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM;IAIrD,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;CAGlD;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAI7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;gBAEjC,OAAO,EAAE,4BAA4B;IA0BlE,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM;IAKpD,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAmChD,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOtD,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,MAAM;CAUf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAChB,MAAM,qBAAqB,CAM7B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,MAAM,qBAAqB,CAK7B"}

package/dist/sparql/timeoutPolicy.js

@@ -0,0 +1,138 @@
+/**
+ * Returns the same timeout for every request. Use this as the
+ * backwards-compatible default for callers that don’t want adaptive
+ * behaviour.
+ */
+export class ConstantTimeoutPolicy {
+    timeoutMs;
+    constructor(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new Error(`ConstantTimeoutPolicy: timeoutMs must be a positive finite number, received ${timeoutMs}`);
+        }
+    }
+    beforeRequest(_context) {
+        return this.timeoutMs;
+    }
+    afterRequest(_context) {
+        // Constant policy is stateless — outcomes never affect future budgets.
+    }
+}
+/**
+ * Adaptive per-endpoint policy: after {@link AdaptiveTimeoutPolicyOptions.tightenAfterTimeouts}
+ * consecutive timeouts on the same endpoint, subsequent requests use the
+ * tightened budget so the pipeline fast-fails instead of waiting out the
+ * full default budget. A single successful request relaxes the endpoint
+ * back to the default budget.
+ *
+ * State is in-memory and tied to the policy instance — Pipeline creates a
+ * fresh instance per dataset so one offending dataset doesn’t poison the
+ * next.
+ *
+ * @example
+ * ```ts
+ * const factory = adaptiveTimeoutPolicy({
+ *   defaultMs: 300_000,
+ *   tightenedMs: 10_000,
+ *   tightenAfterTimeouts: 2,
+ * });
+ * ```
+ */
+export class AdaptiveTimeoutPolicy {
+    options;
+    states = new Map();
+    observers = new Set();
+    constructor(options) {
+        this.options = options;
+        if (!Number.isFinite(options.defaultMs) || options.defaultMs <= 0) {
+            throw new Error(`AdaptiveTimeoutPolicy: \`defaultMs\` must be a positive finite number, received ${options.defaultMs}`);
+        }
+        if (!Number.isFinite(options.tightenedMs) || options.tightenedMs <= 0) {
+            throw new Error(`AdaptiveTimeoutPolicy: \`tightenedMs\` must be a positive finite number, received ${options.tightenedMs}`);
+        }
+        if (!(options.tightenedMs < options.defaultMs)) {
+            throw new Error(`AdaptiveTimeoutPolicy: \`tightenedMs\` (${options.tightenedMs}) must be less than \`defaultMs\` (${options.defaultMs})`);
+        }
+        if (!Number.isInteger(options.tightenAfterTimeouts) ||
+            options.tightenAfterTimeouts < 1) {
+            throw new Error(`AdaptiveTimeoutPolicy: \`tightenAfterTimeouts\` must be an integer ≥ 1, received ${options.tightenAfterTimeouts}`);
+        }
+    }
+    beforeRequest(context) {
+        const state = this.stateFor(context.endpoint);
+        return state.tightened ? this.options.tightenedMs : this.options.defaultMs;
+    }
+    afterRequest(context) {
+        const state = this.stateFor(context.endpoint);
+        if (context.outcome === 'ok') {
+            const wasTightened = state.tightened;
+            const priorCount = state.consecutiveTimeouts;
+            state.consecutiveTimeouts = 0;
+            state.tightened = false;
+            if (wasTightened) {
+                this.notify('relax', {
+                    endpoint: context.endpoint,
+                    fromTimeoutMs: this.options.tightenedMs,
+                    toTimeoutMs: this.options.defaultMs,
+                    consecutiveTimeouts: priorCount,
+                });
+            }
+            return;
+        }
+        if (context.outcome === 'timeout') {
+            state.consecutiveTimeouts += 1;
+            if (!state.tightened &&
+                state.consecutiveTimeouts >= this.options.tightenAfterTimeouts) {
+                state.tightened = true;
+                this.notify('tighten', {
+                    endpoint: context.endpoint,
+                    fromTimeoutMs: this.options.defaultMs,
+                    toTimeoutMs: this.options.tightenedMs,
+                    consecutiveTimeouts: state.consecutiveTimeouts,
+                });
+            }
+        }
+        // 'error' is neutral.
+    }
+    subscribe(observer) {
+        this.observers.add(observer);
+        return () => {
+            this.observers.delete(observer);
+        };
+    }
+    stateFor(endpoint) {
+        const key = endpoint.toString();
+        let state = this.states.get(key);
+        if (!state) {
+            state = { tightened: false, consecutiveTimeouts: 0 };
+            this.states.set(key, state);
+        }
+        return state;
+    }
+    notify(kind, event) {
+        for (const observer of this.observers) {
+            const handler = kind === 'tighten' ? observer.onTighten : observer.onRelax;
+            handler?.(event);
+        }
+    }
+}
+/**
+ * Factory returning a fresh {@link ConstantTimeoutPolicy} on every call.
+ * Pass this to {@link PipelineOptions.timeout}.
+ */
+export function constantTimeoutPolicy(timeoutMs) {
+    // Validate eagerly so misconfiguration is caught at factory creation,
+    // not deferred until the first dataset boundary.
+    new ConstantTimeoutPolicy(timeoutMs);
+    return () => new ConstantTimeoutPolicy(timeoutMs);
+}
+/**
+ * Factory returning a fresh {@link AdaptiveTimeoutPolicy} on every call.
+ * Pass this to {@link PipelineOptions.timeout}; the Pipeline invokes
+ * the factory once per dataset so state resets between datasets.
+ */
+export function adaptiveTimeoutPolicy(options) {
+    // Validate eagerly (see {@link constantTimeoutPolicy}).
+    new AdaptiveTimeoutPolicy(options);
+    return () => new AdaptiveTimeoutPolicy(options);
+}

package/dist/stage.d.ts

@@ -2,6 +2,7 @@ import { Dataset, Distribution } from '@lde/dataset';
 import type { Quad } from '@rdfjs/types';
 import type { Executor, VariableBindings } from './sparql/executor.js';
 import { NotSupported } from './sparql/executor.js';
+import type { TimeoutPolicy } from './sparql/timeoutPolicy.js';
 import type { Validator } from './validator.js';
 import type { Writer } from './writer/writer.js';
 /** Transforms a quad stream, optionally using dataset metadata. */
@@ -40,6 +41,18 @@ export interface StageOptions {
 }
 export interface RunOptions {
     onProgress?: (itemsProcessed: number, quadsGenerated: number) => void;
+    /**
+     * Per-dataset {@link TimeoutPolicy} threaded through to executors and
+     * item selectors. The Pipeline owns lifecycle (factory invocation per
+     * dataset), so a single policy instance covers all stages and child
+     * stages within one dataset.
+     */
+    timeout?: TimeoutPolicy;
+}
+/** Options accepted by {@link ItemSelector.select}. */
+export interface SelectOptions {
+    /** Per-call timeout policy. */
+    timeout?: TimeoutPolicy;
 }
 export declare class Stage {
     readonly name: string;
@@ -63,6 +76,6 @@ export declare class Stage {
 }
 /** Selects items (as variable bindings) for executors to process. Pagination is an implementation detail. */
 export interface ItemSelector {
-    select(distribution: Distribution, batchSize?: number): AsyncIterable<VariableBindings>;
+    select(distribution: Distribution, batchSize?: number, options?: SelectOptions): AsyncIterable<VariableBindings>;
 }
 //# sourceMappingURL=stage.d.ts.map

package/dist/stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,OAAO,EAAE,OAAO,KACb,aAAa,CAAC,IAAI,CAAC,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,SAAS,CAAC;QACrB,iEAAiE;QACjE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;KACvC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;gBAE7C,OAAO,EAAE,YAAY;IAYjC,mDAAmD;IACnD,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAEK,GAAG,CACP,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;YAkDjB,eAAe;IAyJ7B;;;OAGG;YACW,cAAc;YAqBd,UAAU;CAqBzB;AAUD,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,MAAM,CACJ,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpC"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,OAAO,EAAE,OAAO,KACb,aAAa,CAAC,IAAI,CAAC,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,qFAAqF;IACrF,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,SAAS,CAAC;QACrB,iEAAiE;QACjE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;KACvC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;gBAE7C,OAAO,EAAE,YAAY;IAYjC,mDAAmD;IACnD,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAEK,GAAG,CACP,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;YAqDjB,eAAe;IAwJ7B;;;OAGG;YACW,cAAc;YAqBd,UAAU;CAwBzB;AAUD,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,MAAM,CACJ,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpC"}

package/dist/stage.js

@@ -25,10 +25,13 @@ export class Stage {
         return this.validation?.validator;
     }
     async run(dataset, distribution, writer, options) {
+        const timeout = options?.timeout;
         if (this.itemSelector) {
-            return this.runWithSelector(this.itemSelector.select(distribution, this.batchSize), dataset, distribution, writer, options);
+            return this.runWithSelector(this.itemSelector.select(distribution, this.batchSize, {
+                timeout,
+            }), dataset, distribution, writer, options);
         }
-        const streams = await this.executeAll(dataset, distribution);
+        const streams = await this.executeAll(dataset, distribution, timeout);
         if (streams instanceof NotSupported) {
             return streams;
         }
@@ -116,7 +119,10 @@ export class Stage {
                     track((async () => {
                         // Run all executors for this batch in parallel.
                         const executorOutputs = await Promise.all(this.executors.map(async (executor) => {
-                            const result = await executor.execute(dataset, distribution, { bindings });
+                            const result = await executor.execute(dataset, distribution, {
+                                bindings,
+                                timeout: options?.timeout,
+                            });
                             if (result instanceof NotSupported)
                                 return [];
                             hasResults = true;
@@ -197,8 +203,8 @@ export class Stage {
         // 'skip': discard
         return [];
     }
-    async executeAll(dataset, distribution) {
-        const results = await Promise.all(this.executors.map((executor) => executor.execute(dataset, distribution)));
+    async executeAll(dataset, distribution, timeout) {
+        const results = await Promise.all(this.executors.map((executor) => executor.execute(dataset, distribution, { timeout })));
         const streams = [];
         for (const result of results) {
             if (!(result instanceof NotSupported)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.30.1",
+  "version": "0.30.3",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/pipeline"
@@ -26,7 +26,7 @@
   "dependencies": {
     "@lde/dataset": "0.7.4",
     "@lde/dataset-registry-client": "0.8.0",
-    "@lde/distribution-probe": "0.1.3",
+    "@lde/distribution-probe": "0.1.4",
     "@lde/sparql-importer": "0.6.2",
     "@lde/sparql-server": "0.4.11",
     "@rdfjs/types": "^2.0.1",