@origintrail-official/dkg-storage 10.0.5 → 10.0.7

package/README.md

@@ -66,6 +66,47 @@ For heavy / production workloads, prefer an out-of-process SPARQL server
 (`sparql-http` or `blazegraph`), which handles reads and writes concurrently
 and keeps the daemon responsive under load.
 
+## External-store admission and deadlines
+
+All external adapters share a process-wide priority scheduler. Waiting work is
+bounded independently for `ack`, `normal`, and `background` traffic, and an
+operation rejected before dispatch receives `StoreSchedulerBusyError` with
+`code: STORE_SCHEDULER_BUSY`, `retryable: true`, and a reason of either
+`queue_full` or `queue_wait_timeout`. Because this error is only created before
+the operation closure starts, retrying it cannot duplicate a write that might
+already have reached the store.
+
+| Environment variable | Default | Purpose |
+|---|---:|---|
+| `DKG_STORE_MAX_CONCURRENT` | `8` | Maximum external-store operations in flight. |
+| `DKG_STORE_ACK_RESERVED_SLOTS` | `1` | In-flight capacity reserved for ACK work. |
+| `DKG_STORE_NORMAL_RESERVED_SLOTS` | `1` | Non-ACK capacity kept available for normal work while background operations are in flight. |
+| `DKG_STORE_BACKGROUND_RESERVED_SLOTS` | `1` | Non-ACK capacity reserved for background progress. |
+| `DKG_STORE_QUEUE_LIMIT` | `64` | Maximum waiting operations in each priority queue. |
+| `DKG_STORE_ACK_QUEUE_LIMIT` | common limit | Optional ACK queue override. |
+| `DKG_STORE_NORMAL_QUEUE_LIMIT` | common limit | Optional normal queue override. |
+| `DKG_STORE_BACKGROUND_QUEUE_LIMIT` | common limit | Optional background queue override. |
+| `DKG_STORE_QUEUE_WAIT_TIMEOUT_MS` | `10000` | Maximum pre-dispatch wait before a retryable busy rejection. |
+| `DKG_BLAZEGRAPH_OPERATION_TIMEOUT_MS` | `30000` | Blazegraph end-to-end operation deadline, including scheduler wait, HTTP, response decoding, and mapping. |
+
+Normal and background reserves are normalized against the available non-ACK
+capacity. At least one background slot remains available, and the background
+progress floor is capped to its admission ceiling so conflicting custom values
+cannot leave usable capacity idle.
+
+Blazegraph's deadline can also be set per store, which takes precedence over
+the environment default:
+
+```jsonc
+"store": {
+  "backend": "blazegraph",
+  "options": {
+    "url": "http://127.0.0.1:9999/blazegraph/namespace/dkg/sparql",
+    "timeout": 30000
+  }
+}
+```
+
 ## Internal Dependencies
 
 - `@origintrail-official/dkg-core` — configuration types, logging, constants

package/dist/adapters/blazegraph-nquads.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Blazegraph N-Quads wire encoder.
+ *
+ * A focused boundary for the one structural quirk of Blazegraph's bulk-insert
+ * endpoint: its N-Quads parser reads the request body BYTE-wise as ASCII (the
+ * Content-Type charset is ignored), so any non-ASCII byte is replaced with
+ * U+FFFD before parsing — silent stored-value corruption. Downstream, a
+ * published KA carrying such a literal fails its storage-ACK merkle
+ * recomputation (MERKLE_MISMATCH_IN_SWM) and the publish dies.
+ *
+ * Verified against the stock `lyrasis/blazegraph:2.1.5` image (image CI + the
+ * devnet run). Kept here, separate from the adapter's transport/query/mutation
+ * orchestration, so the wire-format invariant is a single testable unit.
+ */
+/**
+ * Make an assembled N-Quads line ASCII-safe for Blazegraph's bulk-insert
+ * endpoint:
+ *
+ *  - Raw non-ASCII UTF-8 (a 2-byte `é` as much as a 4-byte astral emoji) →
+ *    `\uXXXX` per UTF-16 code unit (astral chars as their surrogate pair) — the
+ *    exact Java-String form Blazegraph itself emits on CONSTRUCT read-back and
+ *    the one encoding that round-trips every scalar, including the
+ *    supplementary plane.
+ *  - In-range `\UXXXXXXXX` escapes (which Blazegraph truncates to their low 16
+ *    bits on parse, e.g. `\U0001F600` 😀 → U+F600) → equivalent `\uXXXX`
+ *    escape(s). Out-of-range `\U` (> U+10FFFF, unrepresentable) passes through.
+ *
+ * `\uXXXX` is a valid UCHAR in both IRIREF and STRING_LITERAL_QUOTED, so the
+ * transform is safe to apply to the whole line. Existing escape sequences are
+ * consumed pairwise (backslash parity), so a literal backslash followed by
+ * `U…` text (`\\U0001F600`) is never mis-rewritten. The transform is line-level
+ * by design — the `\U` normalization and the backslash-parity guard are
+ * properties of the rendered line, not of an individual term.
+ */
+export declare function toBlazegraphAsciiSafeNQuads(line: string): string;
+//# sourceMappingURL=blazegraph-nquads.d.ts.map

package/dist/adapters/blazegraph-nquads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blazegraph-nquads.d.ts","sourceRoot":"","sources":["../../src/adapters/blazegraph-nquads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmChE"}

package/dist/adapters/blazegraph-nquads.js

@@ -0,0 +1,79 @@
+/**
+ * Blazegraph N-Quads wire encoder.
+ *
+ * A focused boundary for the one structural quirk of Blazegraph's bulk-insert
+ * endpoint: its N-Quads parser reads the request body BYTE-wise as ASCII (the
+ * Content-Type charset is ignored), so any non-ASCII byte is replaced with
+ * U+FFFD before parsing — silent stored-value corruption. Downstream, a
+ * published KA carrying such a literal fails its storage-ACK merkle
+ * recomputation (MERKLE_MISMATCH_IN_SWM) and the publish dies.
+ *
+ * Verified against the stock `lyrasis/blazegraph:2.1.5` image (image CI + the
+ * devnet run). Kept here, separate from the adapter's transport/query/mutation
+ * orchestration, so the wire-format invariant is a single testable unit.
+ */
+/**
+ * Make an assembled N-Quads line ASCII-safe for Blazegraph's bulk-insert
+ * endpoint:
+ *
+ *  - Raw non-ASCII UTF-8 (a 2-byte `é` as much as a 4-byte astral emoji) →
+ *    `\uXXXX` per UTF-16 code unit (astral chars as their surrogate pair) — the
+ *    exact Java-String form Blazegraph itself emits on CONSTRUCT read-back and
+ *    the one encoding that round-trips every scalar, including the
+ *    supplementary plane.
+ *  - In-range `\UXXXXXXXX` escapes (which Blazegraph truncates to their low 16
+ *    bits on parse, e.g. `\U0001F600` 😀 → U+F600) → equivalent `\uXXXX`
+ *    escape(s). Out-of-range `\U` (> U+10FFFF, unrepresentable) passes through.
+ *
+ * `\uXXXX` is a valid UCHAR in both IRIREF and STRING_LITERAL_QUOTED, so the
+ * transform is safe to apply to the whole line. Existing escape sequences are
+ * consumed pairwise (backslash parity), so a literal backslash followed by
+ * `U…` text (`\\U0001F600`) is never mis-rewritten. The transform is line-level
+ * by design — the `\U` normalization and the backslash-parity guard are
+ * properties of the rendered line, not of an individual term.
+ */
+export function toBlazegraphAsciiSafeNQuads(line) {
+    let out = '';
+    for (let i = 0; i < line.length; i++) {
+        const code = line.charCodeAt(i);
+        if (code === 0x5c /* backslash */) {
+            // In-range \UXXXXXXXX → equivalent \uXXXX escape(s) Blazegraph parses
+            // correctly. Out-of-range \U (> U+10FFFF, unrepresentable) passes through.
+            if (line[i + 1] === 'U') {
+                const hex = line.slice(i + 2, i + 10);
+                if (/^[0-9A-Fa-f]{8}$/.test(hex)) {
+                    const cp = parseInt(hex, 16);
+                    if (cp <= 0x10ffff) {
+                        out += escapeUtf16CodeUnits(String.fromCodePoint(cp));
+                        i += 9;
+                        continue;
+                    }
+                }
+            }
+            // Any other escape: copy the pair verbatim so the escaped char is never
+            // re-inspected (preserves backslash parity for the \U check above).
+            out += line[i];
+            if (i + 1 < line.length) {
+                const nextCode = line.charCodeAt(i + 1);
+                out += nextCode >= 0x7f ? escapeUtf16CodeUnits(line[i + 1]) : line[i + 1];
+                i++;
+            }
+            continue;
+        }
+        if (code >= 0x7f) {
+            out += escapeUtf16CodeUnits(line[i]);
+            continue;
+        }
+        out += line[i];
+    }
+    return out;
+}
+/** `\uXXXX` escape per UTF-16 code unit (surrogate halves stay split). */
+function escapeUtf16CodeUnits(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        out += `\\u${s.charCodeAt(i).toString(16).toUpperCase().padStart(4, '0')}`;
+    }
+    return out;
+}
+//# sourceMappingURL=blazegraph-nquads.js.map

package/dist/adapters/blazegraph-nquads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blazegraph-nquads.js","sourceRoot":"","sources":["../../src/adapters/blazegraph-nquads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,IAAI,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YAClC,sEAAsE;YACtE,2EAA2E;YAC3E,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;gBACtC,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBACjC,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;oBAC7B,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;wBACnB,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;wBACtD,CAAC,IAAI,CAAC,CAAC;wBACP,SAAS;oBACX,CAAC;gBACH,CAAC;YACH,CAAC;YACD,wEAAwE;YACxE,oEAAoE;YACpE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;gBACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACxC,GAAG,IAAI,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC1E,CAAC,EAAE,CAAC;YACN,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,GAAG,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,SAAS;QACX,CAAC;QACD,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0EAA0E;AAC1E,SAAS,oBAAoB,CAAC,CAAS;IACrC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/adapters/blazegraph.d.ts

@@ -1,4 +1,9 @@
-import type { TripleStore, Quad as DKGQuad, QueryOptions, StorePressureSnapshot, TripleStoreQueryOptions, QueryResult } from '../triple-store.js';
+import type { TripleStore, Quad as DKGQuad, QueryOptions, UpdateOptions, StorePressureSnapshot, TripleStoreQueryOptions, QueryResult } from '../triple-store.js';
+export declare const DEFAULT_BLAZEGRAPH_OPERATION_TIMEOUT_MS = 30000;
+export interface BlazegraphStoreOptions {
+    /** End-to-end timeout including scheduler wait, HTTP work, and response decoding. */
+    timeout?: number;
+}
 /**
  * BlazegraphStore — TripleStore adapter backed by a remote Blazegraph
  * SPARQL endpoint over HTTP.  Works with any Blazegraph 2.x instance
@@ -10,7 +15,8 @@ import type { TripleStore, Quad as DKGQuad, QueryOptions, StorePressureSnapshot,
 export declare class BlazegraphStore implements TripleStore {
     readonly queryCancellation: "interruptible";
     private readonly url;
-    constructor(url: string);
+    private readonly operationTimeoutMs;
+    constructor(url: string, options?: BlazegraphStoreOptions);
     private runStoreWork;
     getPressureSnapshot(): StorePressureSnapshot;
     insert(quads: DKGQuad[], options?: QueryOptions): Promise<void>;
@@ -27,7 +33,9 @@ export declare class BlazegraphStore implements TripleStore {
      * delete with two full-graph `countQuads` scans (see above), which is
      * prohibitive on a CPU-pegged core.
      */
-    update(sparql: string, options?: QueryOptions): Promise<void>;
+    update(sparql: string, options?: UpdateOptions): Promise<void>;
+    replaceGraph(graphUri: string, quads: DKGQuad[], options?: QueryOptions): Promise<void>;
+    replaceGraphAndSubject(graphUri: string, graphQuads: DKGQuad[], metaGraphUri: string, metadataSubject: string, metadataQuads: DKGQuad[], options?: QueryOptions): Promise<void>;
     query(sparql: string, options?: TripleStoreQueryOptions): Promise<QueryResult>;
     private queryConstruct;
     hasGraph(graphUri: string, options?: QueryOptions): Promise<boolean>;

package/dist/adapters/blazegraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blazegraph.d.ts","sourceRoot":"","sources":["../../src/adapters/blazegraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,IAAI,IAAI,OAAO,EACf,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EAIZ,MAAM,oBAAoB,CAAC;AAM5B;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,iBAAiB,EAAG,eAAe,CAAU;IAEtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM;IAIvB,OAAO,CAAC,YAAY;IAapB,mBAAmB,IAAI,qBAAqB;IAQtC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB/D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BnF,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBtG;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;YAwDtE,cAAc;IAuBtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAQpE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlE,UAAU,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAahE,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,YAAY;CAwB3B"}
+{"version":3,"file":"blazegraph.d.ts","sourceRoot":"","sources":["../../src/adapters/blazegraph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,IAAI,IAAI,OAAO,EACf,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EAIZ,MAAM,oBAAoB,CAAC;AAuB5B,eAAO,MAAM,uCAAuC,QAAS,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmHD;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,iBAAiB,EAAG,eAAe,CAAU;IAEtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAEhC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IAK7D,OAAO,CAAC,YAAY;IAmCpB,mBAAmB,IAAI,qBAAqB;IAQtC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B/D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BnF,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBtG;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC;IAwBV,sBAAsB,CAC1B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,OAAO,EAAE,EACrB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,OAAO,EAAE,EACxB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC;IAgCV,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;YAqDtE,cAAc;IAiCtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAQpE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlE,UAAU,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAehE,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAQd,YAAY;CA2B3B"}

package/dist/adapters/blazegraph.js

@@ -1,7 +1,111 @@
+import { performance } from 'node:perf_hooks';
 import { registerTripleStoreAdapter } from '../triple-store.js';
 import { buildBlankNodeSafeDelete } from './sparql-http.js';
-import { assertQuadLiteralsMutf8Safe, JAVA_WRITE_UTF_MAX_BYTES } from '@origintrail-official/dkg-core';
+import { formatSparqlJsonBindings, } from './sparql-json-results.js';
+import { toBlazegraphAsciiSafeNQuads } from './blazegraph-nquads.js';
+import { SPARQL_QUERY_CONTENT_TYPE, SPARQL_UPDATE_CONTENT_TYPE } from './sparql-content-types.js';
+import { assertQuadLiteralsMutf8Safe, getMetrics, JAVA_WRITE_UTF_MAX_BYTES, } from '@origintrail-official/dkg-core';
 import { externalStorePriorityScheduler } from '../store-priority-scheduler.js';
+import { buildAtomicGraphAndSubjectReplaceUpdate, buildAtomicGraphReplaceUpdate, isAtomicGraphReplaceStagingGraph, } from '../atomic-graph-replace.js';
+import { quadToNQuad } from '../bounded-rdf.js';
+import { readResponseTextBounded } from '../http-response-limit.js';
+export const DEFAULT_BLAZEGRAPH_OPERATION_TIMEOUT_MS = 30_000;
+function parsePositiveIntegerEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function resolveOperationTimeout(configured) {
+    if (configured === undefined) {
+        return parsePositiveIntegerEnv('DKG_BLAZEGRAPH_OPERATION_TIMEOUT_MS', DEFAULT_BLAZEGRAPH_OPERATION_TIMEOUT_MS);
+    }
+    if (!Number.isInteger(configured) || configured <= 0) {
+        throw new Error('BlazegraphStore timeout must be a positive integer in milliseconds');
+    }
+    return configured;
+}
+function abortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error(String(reason ?? 'aborted'));
+}
+function createStoreOperationDeadline(timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const deadlineAt = performance.now() + timeoutMs;
+    let timer;
+    let callerAttached = false;
+    const timeoutError = () => new DOMException(`Blazegraph operation exceeded its ${timeoutMs}ms deadline`, 'TimeoutError');
+    const detachCaller = () => {
+        if (!callerAttached)
+            return;
+        callerAttached = false;
+        callerSignal?.removeEventListener('abort', onCallerAbort);
+    };
+    const onCallerAbort = () => {
+        detachCaller();
+        controller.abort(callerSignal?.reason);
+    };
+    if (callerSignal?.aborted) {
+        controller.abort(callerSignal.reason);
+    }
+    else {
+        if (callerSignal) {
+            callerAttached = true;
+            callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            detachCaller();
+            controller.abort(timeoutError());
+        }, timeoutMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    }
+    const check = () => {
+        if (controller.signal.aborted)
+            throw abortError(controller.signal);
+        if (performance.now() < deadlineAt)
+            return;
+        const error = timeoutError();
+        detachCaller();
+        controller.abort(error);
+        throw error;
+    };
+    const waitFor = async (work) => {
+        let result;
+        try {
+            // Do not race the operation against the abort signal here. The signal is
+            // already passed to fetch (and therefore to its response body), so the
+            // underlying promise settles only after the HTTP stack has processed the
+            // cancellation. Racing would reject the scheduler task immediately and
+            // release its admission slot while the prior Blazegraph request could
+            // still be unwinding server-side, allowing a retry to overlap it.
+            result = await work;
+        }
+        catch (error) {
+            // The timer callback may be delayed by synchronous response processing.
+            // Re-check the monotonic deadline before preserving an underlying error
+            // so elapsed operations still surface the deadline's TimeoutError.
+            check();
+            throw error;
+        }
+        check();
+        return result;
+    };
+    return {
+        signal: controller.signal,
+        waitFor,
+        check,
+        dispose: () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            detachCaller();
+        },
+    };
+}
 /**
  * BlazegraphStore — TripleStore adapter backed by a remote Blazegraph
  * SPARQL endpoint over HTTP.  Works with any Blazegraph 2.x instance
@@ -13,11 +117,35 @@ import { externalStorePriorityScheduler } from '../store-priority-scheduler.js';
 export class BlazegraphStore {
     queryCancellation = 'interruptible';
     url;
-    constructor(url) {
+    operationTimeoutMs;
+    constructor(url, options = {}) {
         this.url = url.replace(/\/$/, '');
+        this.operationTimeoutMs = resolveOperationTimeout(options.timeout);
     }
     runStoreWork(operation, options, work) {
-        return externalStorePriorityScheduler.run(options?.priority, options?.source ?? `blazegraph.${operation}`, work, options?.signal);
+        const deadline = createStoreOperationDeadline(this.operationTimeoutMs, options?.signal);
+        const source = options?.source ?? `blazegraph.${operation}`;
+        let admitted = false;
+        const scheduled = externalStorePriorityScheduler.run(options?.priority, source, async () => {
+            admitted = true;
+            deadline.check();
+            const result = await work(deadline);
+            deadline.check();
+            return result;
+        }, deadline.signal);
+        return scheduled
+            .catch((error) => {
+            // This runs only after the admitted work promise has settled. Combined
+            // with StoreOperationDeadline.waitFor awaiting the real fetch/body
+            // promise, the metric means transport cleanup completed before the
+            // caller can launch a retry. Queued work that expired before admission
+            // is intentionally excluded.
+            if (admitted && deadline.signal.aborted) {
+                getMetrics().storeCancellationCompletedTotal.add(1, { operation, source });
+            }
+            throw error;
+        })
+            .finally(deadline.dispose);
     }
     getPressureSnapshot() {
         return externalStorePriorityScheduler.snapshot;
@@ -28,24 +156,30 @@ export class BlazegraphStore {
     async insert(quads, options) {
         if (quads.length === 0)
             return;
-        assertQuadLiteralsMutf8Safe(quads, {
-            maxBytes: JAVA_WRITE_UTF_MAX_BYTES,
-            label: 'BlazegraphStore.insert',
-        });
-        const nquads = quads.map(quadToNQuad).join('\n') + '\n';
-        const res = await this.runStoreWork('insert', {
+        await this.runStoreWork('insert', {
             ...options,
             source: options?.source ?? 'blazegraph.insert',
-        }, async () => fetch(this.url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'text/x-nquads' },
-            body: nquads,
-            signal: options?.signal,
-        }));
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new Error(`Blazegraph insert failed (${res.status}): ${text.slice(0, 200)}`);
-        }
+        }, async (deadline) => {
+            assertQuadLiteralsMutf8Safe(quads, {
+                maxBytes: JAVA_WRITE_UTF_MAX_BYTES,
+                label: 'BlazegraphStore.insert',
+            });
+            // Serialize only after scheduler admission. A blocked store therefore
+            // retains the caller's quad array, not an additional potentially-large
+            // N-Quads copy for every waiting insert.
+            const nquads = quads.map(quadToBlazegraphNQuad).join('\n') + '\n';
+            deadline.check();
+            const res = await deadline.waitFor(fetch(this.url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'text/x-nquads' },
+                body: nquads,
+                signal: deadline.signal,
+            }));
+            if (!res.ok) {
+                const text = await deadline.waitFor(res.text().catch(() => ''));
+                throw new Error(`Blazegraph insert failed (${res.status}): ${text.slice(0, 200)}`);
+            }
+        });
     }
     async delete(quads, options) {
         if (quads.length === 0)
@@ -109,21 +243,47 @@ export class BlazegraphStore {
     async update(sparql, options) {
         await this.sparqlUpdate(sparql, { ...options, source: options?.source ?? 'blazegraph.update' }, 'update');
     }
+    async replaceGraph(graphUri, quads, options) {
+        assertQuadLiteralsMutf8Safe(quads, {
+            maxBytes: JAVA_WRITE_UTF_MAX_BYTES,
+            label: 'BlazegraphStore.replaceGraph',
+        });
+        const plan = buildAtomicGraphReplaceUpdate(graphUri, quads);
+        try {
+            await this.sparqlUpdate(plan.update, { ...options, source: options?.source ?? 'blazegraph.replaceGraph' }, 'replaceGraph');
+        }
+        catch (error) {
+            if (plan.cleanup) {
+                await this.sparqlUpdate(plan.cleanup, { ...options, source: 'blazegraph.replaceGraph.cleanup' }, 'replaceGraphCleanup').catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    async replaceGraphAndSubject(graphUri, graphQuads, metaGraphUri, metadataSubject, metadataQuads, options) {
+        assertQuadLiteralsMutf8Safe([...graphQuads, ...metadataQuads], {
+            maxBytes: JAVA_WRITE_UTF_MAX_BYTES,
+            label: 'BlazegraphStore.replaceGraphAndSubject',
+        });
+        const plan = buildAtomicGraphAndSubjectReplaceUpdate(graphUri, graphQuads, metaGraphUri, metadataSubject, metadataQuads);
+        try {
+            await this.sparqlUpdate(plan.update, { ...options, source: options?.source ?? 'blazegraph.replaceGraphAndSubject' }, 'replaceGraphAndSubject');
+        }
+        catch (error) {
+            await this.sparqlUpdate(plan.cleanup, { ...options, source: 'blazegraph.replaceGraphAndSubject.cleanup' }, 'replaceGraphAndSubjectCleanup').catch(() => undefined);
+            throw error;
+        }
+    }
     // -------------------------------------------------------------------
     // Queries
     // -------------------------------------------------------------------
     async query(sparql, options) {
-        return this.runStoreWork('query', options, async () => {
-            if (options?.signal?.aborted) {
-                const reason = options.signal.reason;
-                throw reason instanceof Error ? reason : new Error(String(reason ?? 'aborted'));
-            }
+        return this.runStoreWork('query', options, async (deadline) => {
             const trimmed = sparql.trim();
             const upper = trimmed.toUpperCase();
             const isAsk = upper.startsWith('ASK');
             const isConstruct = upper.startsWith('CONSTRUCT') || upper.startsWith('DESCRIBE');
             if (isConstruct) {
-                return this.queryConstruct(trimmed, options);
+                return this.queryConstruct(trimmed, deadline, options);
             }
             // Direct POST (W3C SPARQL 1.1 Protocol): send the query as the raw
             // request body with `application/sparql-query` rather than URL-encoded
@@ -132,53 +292,53 @@ export class BlazegraphStore {
             // on stock Blazegraph) and rejects larger payloads with HTTP 400
             // "Unable to parse form content". The direct-POST body is not form
             // parsed, so large queries (e.g. CONSTRUCT/VALUES) are not capped.
-            const res = await fetch(this.url, {
+            // SPARQL_QUERY_CONTENT_TYPE carries charset=utf-8 (see sparql-content-types.ts).
+            const res = await deadline.waitFor(fetch(this.url, {
                 method: 'POST',
                 headers: {
-                    'Content-Type': 'application/sparql-query',
+                    'Content-Type': SPARQL_QUERY_CONTENT_TYPE,
                     Accept: 'application/sparql-results+json',
                 },
                 body: trimmed,
-                signal: options?.signal,
-            });
+                signal: deadline.signal,
+            }));
             if (!res.ok) {
-                const text = await res.text().catch(() => '');
+                const text = await deadline.waitFor((options?.maxResponseBytes === undefined
+                    ? res.text()
+                    : readResponseTextBounded(res, options.maxResponseBytes)).catch(() => ''));
                 throw new Error(`Blazegraph query failed (${res.status}): ${text.slice(0, 300)}`);
             }
-            const json = (await res.json());
+            const json = options?.maxResponseBytes === undefined
+                ? await deadline.waitFor(res.json())
+                : JSON.parse(await deadline.waitFor(readResponseTextBounded(res, options.maxResponseBytes)));
             if (isAsk || 'boolean' in json) {
                 return { type: 'boolean', value: json.boolean };
             }
-            const sr = json;
-            const vars = sr.head?.vars ?? [];
-            const bindings = (sr.results?.bindings ?? []).map((row) => {
-                const obj = {};
-                for (const v of vars) {
-                    const cell = row[v];
-                    if (cell)
-                        obj[v] = blazeTermToString(cell);
-                }
-                return obj;
-            });
+            const bindings = formatSparqlJsonBindings(json);
             return { type: 'bindings', bindings };
         });
     }
-    async queryConstruct(sparql, options) {
-        const res = await fetch(this.url, {
+    async queryConstruct(sparql, deadline, options) {
+        const res = await deadline.waitFor(fetch(this.url, {
             method: 'POST',
             headers: {
-                'Content-Type': 'application/sparql-query',
+                'Content-Type': SPARQL_QUERY_CONTENT_TYPE,
                 Accept: 'text/x-nquads, application/n-quads',
             },
             body: sparql,
-            signal: options?.signal,
-        });
+            signal: deadline.signal,
+        }));
         if (!res.ok) {
-            const text = await res.text().catch(() => '');
+            const text = await deadline.waitFor((options?.maxResponseBytes === undefined
+                ? res.text()
+                : readResponseTextBounded(res, options.maxResponseBytes)).catch(() => ''));
             throw new Error(`Blazegraph construct failed (${res.status}): ${text.slice(0, 300)}`);
         }
-        const text = await res.text();
+        const text = await deadline.waitFor(options?.maxResponseBytes === undefined
+            ? res.text()
+            : readResponseTextBounded(res, options.maxResponseBytes));
         const quads = parseNQuadsText(text);
+        deadline.check();
         return { type: 'quads', quads };
     }
     // -------------------------------------------------------------------
@@ -198,7 +358,9 @@ export class BlazegraphStore {
         const r = await this.query('SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } }', options);
         if (r.type !== 'bindings')
             return [];
-        return r.bindings.map((b) => b.g).filter(Boolean);
+        return r.bindings
+            .map((b) => b.g)
+            .filter((graph) => Boolean(graph) && !isAtomicGraphReplaceStagingGraph(graph));
     }
     // -------------------------------------------------------------------
     // Counts
@@ -235,44 +397,38 @@ export class BlazegraphStore {
         // HTTP 400 "Unable to parse form content" — which broke large publishes
         // (a publish issues a DELETE DATA / INSERT over the full quad set). The
         // raw body is not form parsed, so large updates succeed.
-        const res = await this.runStoreWork(operation, options, async () => fetch(this.url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/sparql-update' },
-            body: update,
-            signal: options?.signal,
-        }));
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new Error(`Blazegraph update failed (${res.status}): ${text.slice(0, 300)}`);
-        }
-    }
-}
-function escapeNQuadsLiteral(s) {
-    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
-}
-function blazeTermToString(t) {
-    if (t.type === 'bnode')
-        return `_:${t.value}`;
-    if (t.type === 'literal' || t.type === 'typed-literal') {
-        const escaped = escapeNQuadsLiteral(t.value);
-        if (t['xml:lang'])
-            return `"${escaped}"@${t['xml:lang']}`;
-        if (t.datatype && t.datatype !== 'http://www.w3.org/2001/XMLSchema#string') {
-            return `"${escaped}"^^<${t.datatype}>`;
-        }
-        return `"${escaped}"`;
+        //
+        // SPARQL_UPDATE_CONTENT_TYPE carries charset=utf-8 (see sparql-content-types.ts).
+        await this.runStoreWork(operation, options, async (deadline) => {
+            const res = await deadline.waitFor(fetch(this.url, {
+                method: 'POST',
+                headers: { 'Content-Type': SPARQL_UPDATE_CONTENT_TYPE },
+                body: update,
+                signal: deadline.signal,
+            }));
+            if (!res.ok) {
+                const text = await deadline.waitFor(res.text().catch(() => ''));
+                throw new Error(`Blazegraph update failed (${res.status}): ${text.slice(0, 300)}`);
+            }
+        });
     }
-    return t.value;
 }
 // =====================================================================
 // N-Quad serialisation / parsing helpers (shared with oxigraph adapter)
 // =====================================================================
-function quadToNQuad(q) {
-    const s = formatTerm(q.subject);
-    const p = `<${q.predicate}>`;
-    const o = formatTerm(q.object);
-    const g = q.graph ? ` <${q.graph}>` : '';
-    return `${s} ${p} ${o}${g} .`;
+/**
+ * N-Quads serializer for Blazegraph's bulk-insert wire format: a standard
+ * N-Quads line ({@link quadToNQuad}) made ASCII-safe
+ * ({@link toBlazegraphAsciiSafeNQuads}). This is the single serialization
+ * entry point for the adapter's write path, so the Blazegraph wire-format
+ * invariant lives at the serialization boundary rather than as a separate
+ * post-processing pass a caller must remember to apply. The ASCII-safe pass
+ * operates on the assembled line by design: it normalizes `\U` escapes and
+ * relies on backslash parity across the whole line, both of which are
+ * line-level properties of the rendered N-Quads, not of an individual term.
+ */
+function quadToBlazegraphNQuad(q) {
+    return toBlazegraphAsciiSafeNQuads(quadToNQuad(q));
 }
 function formatTerm(term) {
     if (term.startsWith('"')) {
@@ -394,6 +550,7 @@ registerTripleStoreAdapter('blazegraph', async (opts) => {
     const url = opts?.url;
     if (!url)
         throw new Error('blazegraph adapter requires options.url (SPARQL endpoint)');
-    return new BlazegraphStore(url);
+    const timeout = opts?.timeout;
+    return new BlazegraphStore(url, { timeout });
 });
 //# sourceMappingURL=blazegraph.js.map