@pyxmate/memory 1.17.15 → 1.17.17

package/dist/{chunk-LGNSLDGB.mjs → chunk-JGFDID3B.mjs}

@@ -1,6 +1,7 @@
 import {
+  assertGraphExtractionPayload,
   mergeExtractedEntities
-} from "./chunk-A3L46P2G.mjs";
+} from "./chunk-3OLH3HYR.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {
@@ -10,6 +11,21 @@ var DEFAULTS = {
 };
 var TAXONOMY_MAX_CATEGORIES = 10;
 
+// ../shared/src/document-source.ts
+import { createHash } from "crypto";
+function documentSource(prefix, documentKey) {
+  return `${prefix}:${createHash("sha256").update(documentKey).digest("hex")}`;
+}
+function documentGraphSource(documentKey) {
+  return documentSource("document-graph", documentKey);
+}
+function documentContentSource(documentKey) {
+  return documentSource("document-content", documentKey);
+}
+function documentImageSource(documentKey) {
+  return documentSource("document-image", documentKey);
+}
+
 // ../shared/src/mcp/search-response.ts
 var STRIPPED_ENTRY_FIELDS = /* @__PURE__ */ new Set(["contentHash", "embedding", "tenantId", "userId", "teamId"]);
 function isRecord(value) {
@@ -227,12 +243,54 @@ var DisabledMemory = class {
 };
 
 // ../client/src/memory-client.ts
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeRetryAfter(retryAfter, retryAfterSeconds) {
+  const exact = typeof retryAfter === "string" ? retryAfter.trim() : "";
+  if (exact) {
+    const parsed = /^\d+$/.test(exact) ? Number(exact) : Math.ceil((Date.parse(exact) - Date.now()) / 1e3);
+    return {
+      retryAfter: exact,
+      ...Number.isSafeInteger(parsed) && parsed >= 0 ? { retryAfterSeconds: parsed } : {}
+    };
+  }
+  return Number.isSafeInteger(retryAfterSeconds) && retryAfterSeconds >= 0 ? { retryAfterSeconds } : {};
+}
+function structuralHttpStatus(error) {
+  if (!isRecord3(error) || typeof error.status !== "number") return void 0;
+  return Number.isSafeInteger(error.status) && error.status >= 400 && error.status < 600 ? error.status : void 0;
+}
+function isFileIngestResult(value) {
+  if (!isRecord3(value)) return false;
+  if (typeof value.filename !== "string" || typeof value.fileType !== "string" || typeof value.chunks !== "number" || !Number.isSafeInteger(value.chunks) || value.chunks < 0 || !Array.isArray(value.entryIds) || !value.entryIds.every((id) => typeof id === "string") || typeof value.totalCharacters !== "number" || !Number.isSafeInteger(value.totalCharacters) || value.totalCharacters < 0) {
+    return false;
+  }
+  if (value.graphAnchorEntryId !== void 0 && typeof value.graphAnchorEntryId !== "string") {
+    return false;
+  }
+  if (value.enrichment !== void 0 && !isRecord3(value.enrichment)) return false;
+  return true;
+}
+function hasEnrichmentCallback(callbacks) {
+  return Boolean(callbacks?.describeImage || callbacks?.extractEntitiesV2);
+}
 var MemoryServerError = class extends Error {
   status;
-  constructor(message, status) {
+  /** Stable machine-readable discriminator returned by the memory server. */
+  code;
+  /** Exact HTTP Retry-After value returned by the memory server. */
+  retryAfter;
+  /** Retry delay normalized to seconds when Retry-After is parseable. */
+  retryAfterSeconds;
+  constructor(message, status, code, retryAfter) {
     super(message);
     this.name = "MemoryServerError";
     this.status = status;
+    this.code = code;
+    const retry = normalizeRetryAfter(retryAfter);
+    this.retryAfter = retry.retryAfter;
+    this.retryAfterSeconds = retry.retryAfterSeconds;
   }
   /** True when the server returned HTTP 404 (not found). */
   get isNotFound() {
@@ -272,12 +330,33 @@ var MemoryClient = class {
   }
   authorityHeaders(options) {
     if (!options) return {};
+    const headers = {};
     const key = options.idempotencyKey;
-    if (key === void 0) return {};
-    if (typeof key !== "string" || key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
-      throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
+    if (key !== void 0) {
+      if (typeof key !== "string" || key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
+        throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
+      }
+      headers["Idempotency-Key"] = key;
+    }
+    for (const [headerName, value] of [
+      ["X-Tenant-Id", options.tenantId],
+      ["X-Namespace-Id", options.namespaceId]
+    ]) {
+      if (value === void 0) continue;
+      const configured = Object.entries(this._authHeaders).find(
+        ([name]) => name.toLowerCase() === headerName.toLowerCase()
+      )?.[1];
+      if (configured !== void 0) {
+        if (configured !== value) {
+          throw new Error(
+            `${headerName} conflicts with the MemoryClient default scope; create a client for the requested scope`
+          );
+        }
+        continue;
+      }
+      headers[headerName] = value;
     }
-    return { "Idempotency-Key": key };
+    return headers;
   }
   async initialize() {
     const response = await fetch(`${this.baseUrl}/health`, {
@@ -424,8 +503,17 @@ var MemoryClient = class {
    * collect the terminal event; there is no separate `ingestFile()` Promise
    * method by design (one wire format, one SDK method).
    */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: NDJSON dispatch + SDK enrichment fan-out is two cooperating paths; documented inline and tested in memory-client-events.test.ts.
   async *ingestFileEvents(file, options) {
+    if (options?.documentKey !== void 0) {
+      if (typeof options.documentKey !== "string" || options.documentKey.trim().length === 0) {
+        throw new Error("ingestFileEvents requires a non-empty documentKey when provided");
+      }
+      if (!options.enrichment?.extractEntitiesV2) {
+        throw new Error(
+          "ingestFileEvents with documentKey requires enrichment.extractEntitiesV2 so the stable graph replacement can be finalized"
+        );
+      }
+    }
     const controller = new AbortController();
     const relayAbort = () => controller.abort(options?.signal?.reason);
     if (options?.signal?.aborted) relayAbort();
@@ -435,243 +523,434 @@ var MemoryClient = class {
       formData.append("file", file);
       if (options?.description) formData.append("description", options.description);
       if (options?.namespaceId) formData.append("namespaceId", options.namespaceId);
+      if (options?.documentKey !== void 0) {
+        formData.append("documentKey", options.documentKey);
+      }
+      if (options?.catalogEntryId !== void 0) {
+        formData.append("catalogEntryId", options.catalogEntryId);
+      }
       const wantsTextWindows = Boolean(options?.enrichment?.extractEntitiesV2);
       const headers = {
         Accept: "application/x-ndjson",
         ...this._authHeaders
       };
       if (wantsTextWindows) headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
-      let res;
-      try {
-        res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
-          method: "POST",
-          body: formData,
-          headers,
-          signal: controller.signal
-        });
-      } catch (err) {
-        yield this.ingestErrorEvent(
-          this.translateFetchError(err, "/api/memory/ingest/file"),
-          "parsing"
-        );
-        return;
-      }
-      const contentType = res.headers.get("content-type") ?? "";
-      if (!contentType.includes("application/x-ndjson")) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError(
-            `Memory server returned ${contentType || "unknown content-type"} instead of application/x-ndjson \u2014 server is older than v0.15.0`,
-            res.status
-          ),
-          "parsing"
-        );
-        return;
+      const raw = yield* this.streamNdjsonUpload(
+        "/api/memory/ingest/file",
+        formData,
+        headers,
+        controller.signal
+      );
+      if (!raw) return;
+      const serverResult = this.fileIngestResultFromEvent({
+        ...raw,
+        schemaVersion: 1,
+        type: "result",
+        stage: "complete"
+      });
+      yield* this.completeIngestFileEvents(file, serverResult, options, controller.signal);
+    } finally {
+      options?.signal?.removeEventListener("abort", relayAbort);
+      controller.abort();
+    }
+  }
+  /**
+   * Graph-only re-enrichment for a document whose chunks are already stored
+   * and searchable but whose graph build failed. Uploads the original to
+   * `/api/memory/graph/enrich/file` (prepare-only — the server performs zero
+   * store/delete before the final graph write), runs the SAME enrichment
+   * callback engine as {@link ingestFileEvents}, then finalizes into one
+   * stable graph anchor keyed by `documentKey`. Repeating the same key
+   * replaces the document's graph references idempotently.
+   *
+   * The terminal `result` is a {@link GraphEnrichResult} event carrying the
+   * ACTUAL persisted graph counts; abort and failures yield a terminal
+   * `error` event instead (the server retains the pending session for retry).
+   */
+  async *graphEnrichFileEvents(file, options) {
+    if (typeof options?.documentKey !== "string" || options.documentKey.trim().length === 0) {
+      throw new Error("graphEnrichFileEvents requires a non-empty documentKey");
+    }
+    if (!options.enrichment?.extractEntitiesV2) {
+      throw new Error(
+        "graphEnrichFileEvents requires enrichment.extractEntitiesV2 \u2014 graph-only re-enrichment is caller-extraction by definition"
+      );
+    }
+    const controller = new AbortController();
+    const relayAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) relayAbort();
+    options.signal?.addEventListener("abort", relayAbort, { once: true });
+    try {
+      const formData = new FormData();
+      formData.append("file", file);
+      formData.append("documentKey", options.documentKey);
+      if (options.catalogEntryId !== void 0) {
+        formData.append("catalogEntryId", options.catalogEntryId);
       }
-      if (!res.body) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError("Memory server returned an empty stream", res.status),
-          "parsing"
+      if (options.namespaceId) formData.append("namespaceId", options.namespaceId);
+      const headers = {
+        Accept: "application/x-ndjson",
+        "X-Pyx-Enrichment-Capabilities": "text_windows_v1",
+        ...this._authHeaders
+      };
+      const raw = yield* this.streamNdjsonUpload(
+        "/api/memory/graph/enrich/file",
+        formData,
+        headers,
+        controller.signal
+      );
+      if (!raw) return;
+      try {
+        const prepared = raw;
+        if (prepared.purpose !== "graph-only" || !prepared.enrichment) {
+          throw new MemoryServerError(
+            "Graph enrichment prepare returned an unexpected terminal result",
+            0
+          );
+        }
+        const outcome = yield* this.runEnrichmentCallbacks(
+          file,
+          prepared.enrichment,
+          options.enrichment,
+          controller.signal,
+          "graph-only"
         );
-        return;
+        const data = outcome.data;
+        if (data?.purpose !== "graph-only" || !Array.isArray(data.entryIds) || data.entryIds.length !== 1 || typeof data.entryIds[0] !== "string" || data.entryIds[0].length === 0 || typeof data.graphAnchorEntryId !== "string" || data.graphAnchorEntryId.length === 0) {
+          throw new MemoryServerError(
+            "Graph enrichment finalization returned an unexpected result",
+            0
+          );
+        }
+        yield { schemaVersion: 1, type: "result", stage: "complete", ...data };
+      } catch (err) {
+        yield this.ingestErrorEvent(err, "enrichment");
       }
-      const reader = res.body.getReader();
-      const decoder = new TextDecoder();
-      let buffer = "";
-      let currentStage = "parsing";
-      let serverResult = null;
+    } finally {
+      options.signal?.removeEventListener("abort", relayAbort);
+      controller.abort();
+    }
+  }
+  /**
+   * POST a multipart body to an NDJSON streaming endpoint and relay its
+   * progress/heartbeat events. Returns the raw terminal `result` record, or
+   * null after yielding a terminal error (transport failure, server error
+   * event, non-NDJSON response, stream ending without a result). One
+   * implementation for both streaming surfaces so the wire protocol cannot
+   * fork.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one stateful NDJSON reader validates and relays both ingest and graph-only stream envelopes
+  async *streamNdjsonUpload(path, formData, headers, signal) {
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        body: formData,
+        headers,
+        signal
+      });
+    } catch (err) {
+      yield this.ingestErrorEvent(this.translateFetchError(err, path), "parsing");
+      return null;
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!res.ok) {
+      let error;
       try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop() ?? "";
-          for (const line of lines) {
-            if (!line.trim()) continue;
-            const raw = JSON.parse(line);
-            const type = raw.type;
-            if (type === "progress" || type === "heartbeat") {
-              const stage = this.normalizeActiveIngestStage(raw.stage);
-              if (!stage) continue;
-              currentStage = stage;
-              yield { ...raw, schemaVersion: 1, type, stage };
-              continue;
-            }
-            if (type === "result") {
-              serverResult = this.fileIngestResultFromEvent({
-                ...raw,
-                schemaVersion: 1,
-                type: "result",
-                stage: "complete"
-              });
-              break;
-            }
-            if (type === "error") {
-              yield {
-                schemaVersion: 1,
-                type: "error",
-                stage: this.normalizeActiveIngestStage(raw.stage) ?? currentStage,
-                error: typeof raw.error === "string" ? raw.error : "File ingest failed",
-                message: typeof raw.message === "string" ? raw.message : void 0,
-                code: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : void 0,
-                status: typeof raw.status === "number" ? raw.status : void 0
-              };
-              return;
-            }
+        await this.parseApiResponse(res);
+        error = new MemoryServerError(`Memory server error: ${res.status}`, res.status);
+      } catch (cause) {
+        error = cause;
+      }
+      yield this.ingestErrorEvent(error, "parsing");
+      return null;
+    }
+    if (!contentType.includes("application/x-ndjson")) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError(
+          `Memory server returned ${contentType || "unknown content-type"} instead of application/x-ndjson \u2014 server is older than v0.15.0`,
+          res.status
+        ),
+        "parsing"
+      );
+      return null;
+    }
+    if (!res.body) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError("Memory server returned an empty stream", res.status),
+        "parsing"
+      );
+      return null;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentStage = "parsing";
+    let serverResult = null;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const raw = JSON.parse(line);
+          const type = raw.type;
+          if (type === "progress" || type === "heartbeat") {
+            const stage = this.normalizeActiveIngestStage(raw.stage);
+            if (!stage) continue;
+            currentStage = stage;
+            yield { ...raw, schemaVersion: 1, type, stage };
+            continue;
+          }
+          if (type === "result") {
+            serverResult = raw;
+            break;
+          }
+          if (type === "error") {
+            const partialResult = isFileIngestResult(raw.partialResult) ? raw.partialResult : void 0;
+            const retry = normalizeRetryAfter(raw.retryAfter, raw.retryAfterSeconds);
+            yield {
+              schemaVersion: 1,
+              type: "error",
+              stage: this.normalizeActiveIngestStage(raw.stage) ?? currentStage,
+              error: typeof raw.error === "string" ? raw.error : "File ingest failed",
+              message: typeof raw.message === "string" ? raw.message : void 0,
+              code: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : void 0,
+              status: typeof raw.status === "number" ? raw.status : void 0,
+              ...retry,
+              ...partialResult ? { partialResult } : {}
+            };
+            return null;
           }
-          if (serverResult) break;
         }
-      } catch (err) {
-        yield this.ingestErrorEvent(err, currentStage);
-        return;
-      } finally {
-        reader.releaseLock();
+        if (serverResult) break;
       }
-      if (!serverResult) {
-        yield this.ingestErrorEvent(
-          new MemoryServerError("File ingest stream ended without a server result", 0),
-          currentStage
-        );
-        return;
-      }
-      yield* this.completeIngestFileEvents(file, serverResult, options, controller.signal);
+    } catch (err) {
+      yield this.ingestErrorEvent(err, currentStage);
+      return null;
     } finally {
-      options?.signal?.removeEventListener("abort", relayAbort);
-      controller.abort();
+      reader.releaseLock();
+    }
+    if (!serverResult) {
+      yield this.ingestErrorEvent(
+        new MemoryServerError("File ingest stream ended without a server result", 0),
+        currentStage
+      );
+      return null;
     }
+    return serverResult;
   }
   /**
-   * Run the SDK-side enrichment phase (image-describe → entity-extract →
-   * `/enrich` POST) for a server result, emitting progress + heartbeat
-   * events around the slow steps and yielding the single terminal
-   * {@link IngestResultEvent} at the end. Skips work cleanly when the
-   * server emitted no enrichment block or the caller wired no callbacks.
+   * Run the SDK-side enrichment phase for an ingest result and yield the
+   * single terminal {@link IngestResultEvent} at the end. Skips work cleanly
+   * when the server emitted no enrichment block or the caller wired no
+   * callbacks. The callback work itself lives in
+   * {@link runEnrichmentCallbacks} — shared with the graph-only surface.
    */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: image-describe / extract-entities-v2 / no-op are documented decision branches; the fan-out covers the v0.15.0 enrichment phase + heartbeat plumbing.
   async *completeIngestFileEvents(file, result, options, signal) {
     try {
-      if (!result.enrichment || !options?.enrichment) {
+      const callbacks = options?.enrichment;
+      if (options?.documentKey !== void 0 && !result.enrichment) {
+        throw new MemoryServerError(
+          "documentKey-aware ingest response omitted required enrichment preparation; stable graph finalization did not run",
+          502
+        );
+      }
+      if (!result.enrichment || !hasEnrichmentCallback(callbacks)) {
         yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
         return;
       }
-      const enrichment = result.enrichment;
-      const { fileId, token, expiresAt, images } = enrichment;
-      const isV2 = "version" in enrichment;
-      const textWindows = isV2 ? enrichment.textWindows : [];
-      const descriptions = [];
-      const describeImage = options.enrichment.describeImage;
-      if (describeImage && images.length > 0) {
-        yield {
-          schemaVersion: 1,
-          type: "progress",
-          stage: "enrichment",
-          filename: file.name,
-          imagesTotal: images.length,
-          imagesDescribed: 0,
-          message: `Describing extracted images (0/${images.length})`
-        };
-        const CONCURRENCY = 5;
-        for (let i = 0; i < images.length; i += CONCURRENCY) {
-          const batch = images.slice(i, i + CONCURRENCY);
-          const batchResults = yield* this.withSdkHeartbeats(
-            "enrichment",
-            Promise.all(
-              batch.map(async (imageMeta) => {
-                const imageRes = await fetch(
-                  `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
-                  { headers: this._authHeaders, signal }
-                );
-                if (!imageRes.ok) {
-                  throw new MemoryServerError(
-                    `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
-                    imageRes.status
-                  );
-                }
-                const imageBuffer = await imageRes.arrayBuffer();
-                const description = await describeImage(imageBuffer, imageMeta);
-                return { imageId: imageMeta.imageId, description };
-              })
-            ),
-            signal
+      const outcome = yield* this.runEnrichmentCallbacks(
+        file,
+        result.enrichment,
+        callbacks,
+        signal,
+        "ingest",
+        options?.documentKey !== void 0
+      );
+      if (outcome.posted) {
+        const enrichData = outcome.data;
+        if (options?.documentKey !== void 0 && !enrichData.graphAnchorEntryId) {
+          throw new MemoryServerError(
+            "documentKey-aware enrichment response omitted graphAnchorEntryId; server does not support stable document replacement",
+            502
           );
-          descriptions.push(...batchResults.filter((d) => d.description.trim().length > 0));
-          yield {
-            schemaVersion: 1,
-            type: "progress",
-            stage: "enrichment",
-            filename: file.name,
-            imagesTotal: images.length,
-            imagesDescribed: descriptions.length,
-            message: `Described ${descriptions.length}/${images.length} images`
-          };
         }
+        result.entryIds.push(...enrichData.entryIds);
+        if (enrichData.graphAnchorEntryId) {
+          result.graphAnchorEntryId = enrichData.graphAnchorEntryId;
+        }
+        if ((enrichData.relationshipsDropped ?? 0) > 0) {
+          result.relationshipsDropped = enrichData.relationshipsDropped;
+          result.droppedRelationships = enrichData.droppedRelationships;
+        }
+        result.chunks += outcome.descriptions.length;
+        result.totalCharacters += outcome.descriptions.reduce(
+          (sum, d) => sum + d.description.length,
+          0
+        );
       }
-      let entities;
-      let relationships;
-      const imageDescriptionTexts = descriptions.map((d) => d.description);
-      if (options.enrichment.extractEntitiesV2 && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
+      delete result.enrichment;
+      yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
+    } catch (err) {
+      yield this.ingestErrorEvent(err, "enrichment", result);
+    }
+  }
+  /**
+   * The ONE enrichment callback engine, shared by {@link ingestFileEvents}
+   * and {@link graphEnrichFileEvents}: fetches extracted images, invokes
+   * `describeImage` with bounded concurrency, invokes `extractEntitiesV2`
+   * exactly once, and POSTs `/files/{fileId}/enrich` — emitting progress and
+   * heartbeat events around each slow step. Throws on any failure; the
+   * purpose-specific wrappers translate that into their terminal error.
+   *
+   * Legacy ingest keeps its existing partial add-on behavior. Graph-only and
+   * documentKey-aware full ingest may replace a prior graph only from a
+   * complete input set (no truncated text windows or undescribed images). A
+   * complete extractor result containing zero entities remains a valid clear.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: image-describe / extract-entities-v2 / no-op are documented decision branches; the fan-out covers the v0.15.0 enrichment phase + heartbeat plumbing.
+  async *runEnrichmentCallbacks(file, enrichment, callbacks, signal, purpose, replaceEmptyGraph = false) {
+    const { fileId, token, expiresAt, images } = enrichment;
+    const isV2 = "version" in enrichment;
+    const textWindows = isV2 ? enrichment.textWindows : [];
+    const textWindowsTruncation = isV2 ? enrichment.textWindowsTruncation : void 0;
+    const requiresCompleteGraphReplacement = purpose === "graph-only" || replaceEmptyGraph;
+    if (requiresCompleteGraphReplacement && textWindowsTruncation?.truncated) {
+      throw new MemoryServerError(
+        `Graph enrichment input was truncated (${textWindowsTruncation.reason ?? "unknown limit"}); prior graph state was preserved and the pending session remains retryable`,
+        422
+      );
+    }
+    const descriptions = [];
+    const describeImage = callbacks.describeImage;
+    if (describeImage && images.length > 0) {
+      yield {
+        schemaVersion: 1,
+        type: "progress",
+        stage: "enrichment",
+        filename: file.name,
+        imagesTotal: images.length,
+        imagesDescribed: 0,
+        message: `Describing extracted images (0/${images.length})`
+      };
+      const CONCURRENCY = 5;
+      for (let i = 0; i < images.length; i += CONCURRENCY) {
+        const batch = images.slice(i, i + CONCURRENCY);
+        const batchResults = yield* this.withSdkHeartbeats(
+          "enrichment",
+          Promise.all(
+            batch.map(async (imageMeta) => {
+              const imageRes = await fetch(
+                `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
+                { headers: this._authHeaders, signal }
+              );
+              if (!imageRes.ok) {
+                throw new MemoryServerError(
+                  `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
+                  imageRes.status
+                );
+              }
+              const imageBuffer = await imageRes.arrayBuffer();
+              const description = await describeImage(imageBuffer, imageMeta);
+              return { imageId: imageMeta.imageId, description };
+            })
+          ),
+          signal
+        );
+        descriptions.push(...batchResults.filter((d) => d.description.trim().length > 0));
         yield {
           schemaVersion: 1,
           type: "progress",
           stage: "enrichment",
           filename: file.name,
-          message: "Extracting entities"
+          imagesTotal: images.length,
+          imagesDescribed: descriptions.length,
+          message: `Described ${descriptions.length}/${images.length} images`
         };
-        const extracted = yield* this.withSdkHeartbeats(
-          "enrichment",
-          options.enrichment.extractEntitiesV2({
-            textWindows,
-            imageDescriptions: imageDescriptionTexts,
-            mimeType: file.type,
-            filename: file.name
-          }),
-          signal
-        );
-        entities = extracted.entities;
-        relationships = extracted.relationships;
-      }
-      const hasGraph = (entities?.length ?? 0) > 0;
-      const hasImages = descriptions.length > 0;
-      if (!hasGraph && !hasImages) {
-        yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
-        return;
       }
+    }
+    if (requiresCompleteGraphReplacement && descriptions.length < images.length) {
+      throw new MemoryServerError(
+        `Graph enrichment described only ${descriptions.length}/${images.length} images; prior graph state was preserved and the pending session remains retryable`,
+        422
+      );
+    }
+    let entities;
+    let relationships;
+    const imageDescriptionTexts = descriptions.map((d) => d.description);
+    if (callbacks.extractEntitiesV2 && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
       yield {
         schemaVersion: 1,
         type: "progress",
         stage: "enrichment",
         filename: file.name,
-        message: "Persisting enrichment"
+        message: "Extracting entities"
       };
-      const enrichRes = yield* this.withSdkHeartbeats(
+      const rawExtracted = yield* this.withSdkHeartbeats(
         "enrichment",
-        fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "X-Enrichment-Token": `${token}:${expiresAt}`,
-            ...this._authHeaders
-          },
-          signal,
-          body: JSON.stringify({ imageDescriptions: descriptions, entities, relationships })
+        callbacks.extractEntitiesV2({
+          textWindows,
+          imageDescriptions: imageDescriptionTexts,
+          mimeType: file.type,
+          filename: file.name
         }),
         signal
       );
-      if (!enrichRes.ok) {
-        const body = await enrichRes.json().catch(() => ({}));
+      let extracted;
+      try {
+        extracted = assertGraphExtractionPayload(rawExtracted, "extractEntitiesV2 result");
+      } catch (error) {
         throw new MemoryServerError(
-          body.error ?? `Enrichment failed: ${enrichRes.status}`,
-          enrichRes.status
+          error instanceof Error ? error.message : "extractEntitiesV2 returned an invalid result",
+          422
         );
       }
-      const enrichData = await this.parseApiResponse(enrichRes);
-      result.entryIds.push(...enrichData.entryIds);
-      result.chunks += descriptions.length;
-      result.totalCharacters += descriptions.reduce((sum, d) => sum + d.description.length, 0);
-      yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
-    } catch (err) {
-      yield this.ingestErrorEvent(err, "enrichment", result);
+      entities = extracted.entities;
+      relationships = extracted.relationships;
+    }
+    const hadExtractionInput = textWindows.length > 0 || imageDescriptionTexts.length > 0;
+    if (purpose === "graph-only" && !hadExtractionInput) {
+      throw new MemoryServerError(
+        "Graph enrichment produced no extractable text or image descriptions; prior graph state was preserved",
+        422
+      );
+    }
+    const hasGraph = (entities?.length ?? 0) > 0;
+    const hasImages = descriptions.length > 0;
+    if (!hasGraph && !hasImages && purpose === "ingest" && !replaceEmptyGraph) {
+      return { posted: false, data: null, descriptions };
     }
+    yield {
+      schemaVersion: 1,
+      type: "progress",
+      stage: "enrichment",
+      filename: file.name,
+      message: "Persisting enrichment"
+    };
+    const enrichRes = yield* this.withSdkHeartbeats(
+      "enrichment",
+      fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Enrichment-Token": `${token}:${expiresAt}`,
+          ...this._authHeaders
+        },
+        signal,
+        body: JSON.stringify({
+          imageDescriptions: descriptions,
+          entities: entities ?? [],
+          relationships: relationships ?? []
+        })
+      }),
+      signal
+    );
+    const data = await this.parseApiResponse(enrichRes);
+    return { posted: true, data, descriptions };
   }
   /**
    * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
@@ -735,15 +1014,20 @@ var MemoryClient = class {
     return result;
   }
   ingestErrorEvent(error, stage, partialResult) {
-    const status = error instanceof MemoryServerError ? error.status : error instanceof Error && error.name === "AbortError" ? 499 : void 0;
+    const structuralError = isRecord3(error) ? error : void 0;
+    const status = error instanceof MemoryServerError ? error.status : error instanceof Error && error.name === "AbortError" ? 499 : structuralHttpStatus(error);
     const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof MemoryServerError ? error.code : void 0;
+    const retry = error instanceof MemoryServerError ? { retryAfter: error.retryAfter, retryAfterSeconds: error.retryAfterSeconds } : normalizeRetryAfter(structuralError?.retryAfter, structuralError?.retryAfterSeconds);
     return {
       schemaVersion: 1,
       type: "error",
       stage,
       error: message,
       message,
-      ...status != null ? { status, code: status } : {},
+      ...status != null ? { status, code: code ?? status } : {},
+      ...retry.retryAfter !== void 0 ? { retryAfter: retry.retryAfter } : {},
+      ...retry.retryAfterSeconds !== void 0 ? { retryAfterSeconds: retry.retryAfterSeconds } : {},
       ...partialResult ? { partialResult } : {}
     };
   }
@@ -751,15 +1035,24 @@ var MemoryClient = class {
    * Get the download URL for an uploaded file.
    * Returns a URL that serves the original file binary with proper Content-Type.
    */
-  getFileDownloadUrl(filename) {
-    return `${this.baseUrl}/api/memory/files/download/${encodeURIComponent(filename)}`;
+  getFileDownloadUrl(filename, options) {
+    const url = new URL(
+      `${this.baseUrl}/api/memory/files/download/${encodeURIComponent(filename)}`
+    );
+    if (options?.documentKey !== void 0) {
+      url.searchParams.set("documentKey", options.documentKey);
+    }
+    if (options?.namespaceId !== void 0) {
+      url.searchParams.set("namespaceId", options.namespaceId);
+    }
+    return url.toString();
   }
   /**
    * Download an uploaded file by filename.
    * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
    */
-  async downloadFile(filename) {
-    const url = this.getFileDownloadUrl(filename);
+  async downloadFile(filename, options) {
+    const url = this.getFileDownloadUrl(filename, options);
     const res = await fetch(url, { headers: this._authHeaders });
     if (!res.ok) {
       throw new MemoryServerError(`File download failed: ${res.status}`, res.status);
@@ -837,10 +1130,10 @@ var MemoryClient = class {
   async repairGraph() {
     return this.fetchApi("/api/memory/graph/repair", { method: "POST" });
   }
-  async deleteBySource(source) {
+  async deleteBySource(source, authority) {
     const result = await this.fetchApi(
       `/api/memory/source/${this.encodePathSegment(source)}`,
-      { method: "DELETE" }
+      { method: "DELETE", headers: this.authorityHeaders(authority) }
     );
     return result.deleted;
   }
@@ -853,14 +1146,20 @@ var MemoryClient = class {
       }
     );
   }
-  async queryAsOf(asOfDate, filters = {}) {
+  async queryAsOf(asOfDate, filters = {}, authority) {
+    if (filters.cursor !== void 0 && filters.offset !== void 0) {
+      throw new Error("queryAsOf cursor and offset are mutually exclusive");
+    }
     const params = new URLSearchParams({ asOf: asOfDate });
     if (filters.type) params.set("type", filters.type);
     if (filters.agentId) params.set("agentId", filters.agentId);
     if (filters.source) params.set("source", filters.source);
     if (filters.limit) params.set("limit", String(filters.limit));
+    if (filters.offset !== void 0) params.set("offset", String(filters.offset));
+    if (filters.cursor !== void 0) params.set("cursor", filters.cursor);
     const result = await this.fetchApi(
-      `/api/memory/query-as-of?${params}`
+      `/api/memory/query-as-of?${params}`,
+      { headers: this.authorityHeaders(authority) }
     );
     return result.entries;
   }
@@ -902,11 +1201,15 @@ var MemoryClient = class {
     return result.entries;
   }
   async queryByEventTime(startTime, endTime, filters = {}) {
+    if (filters.cursor !== void 0) {
+      throw new Error("queryByEventTime does not support a createdAt cursor; use offset");
+    }
     const params = new URLSearchParams({ startTime, endTime });
     if (filters.type) params.set("type", filters.type);
     if (filters.agentId) params.set("agentId", filters.agentId);
     if (filters.source) params.set("source", filters.source);
     if (filters.limit) params.set("limit", String(filters.limit));
+    if (filters.offset !== void 0) params.set("offset", String(filters.offset));
     const result = await this.fetchApi(
       `/api/memory/query-by-event-time?${params}`
     );
@@ -1030,23 +1333,33 @@ var MemoryClient = class {
   }
   /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
   async parseApiResponse(res) {
+    const retryAfter = res.headers.get("Retry-After") ?? void 0;
     let body;
     try {
       body = await res.json();
     } catch {
       throw new MemoryServerError(
         `Memory server error: invalid JSON response (${res.status})`,
-        res.status
+        res.status,
+        void 0,
+        retryAfter
       );
     }
-    if (!body?.success || body.data == null) {
+    if (!res.ok || !body?.success || body.data == null) {
       if (res.ok && body?.error === void 0) {
         throw new MemoryServerError(
           `Memory server returned HTTP ${res.status} without the expected { success, data } API envelope. Check that the base URL points to a pyx-memory instance server; hosted pyx-memory access uses MCP.`,
-          res.status
+          res.status,
+          void 0,
+          retryAfter
         );
       }
-      throw new MemoryServerError(body?.error ?? `Memory server error: ${res.status}`, res.status);
+      throw new MemoryServerError(
+        body?.error ?? `Memory server error: ${res.status}`,
+        res.status,
+        body?.code,
+        retryAfter
+      );
     }
     return body.data;
   }
@@ -1055,6 +1368,9 @@ var MemoryClient = class {
 export {
   DEFAULTS,
   TAXONOMY_MAX_CATEGORIES,
+  documentGraphSource,
+  documentContentSource,
+  documentImageSource,
   projectSearchResponseForMcp,
   secretElevationNoticeFor,
   withSecretElevationNotice,