@arke-institute/sdk 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,35 +1,630 @@
-"use strict";
 var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+
+// src/upload/utils/errors.ts
+function isRetryableError(error) {
+  if (error instanceof NetworkError) {
+    return true;
   }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+  if (error instanceof WorkerAPIError) {
+    return error.statusCode ? error.statusCode >= 500 : false;
+  }
+  if (error instanceof UploadError) {
+    if (error.statusCode) {
+      return error.statusCode >= 500 || error.statusCode === 429;
+    }
+    return false;
+  }
+  if (error.code === "ECONNRESET" || error.code === "ETIMEDOUT" || error.code === "ENOTFOUND" || error.code === "ECONNREFUSED") {
+    return true;
+  }
+  return false;
+}
+var WorkerAPIError, UploadError, ValidationError, NetworkError, ScanError;
+var init_errors = __esm({
+  "src/upload/utils/errors.ts"() {
+    "use strict";
+    WorkerAPIError = class extends Error {
+      constructor(message, statusCode, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "WorkerAPIError";
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+    UploadError = class extends Error {
+      constructor(message, fileName, statusCode, cause) {
+        super(message);
+        this.fileName = fileName;
+        this.statusCode = statusCode;
+        this.cause = cause;
+        this.name = "UploadError";
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+    ValidationError = class extends Error {
+      constructor(message, field) {
+        super(message);
+        this.field = field;
+        this.name = "ValidationError";
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+    NetworkError = class extends Error {
+      constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "NetworkError";
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+    ScanError = class extends Error {
+      constructor(message, path2) {
+        super(message);
+        this.path = path2;
+        this.name = "ScanError";
+        Error.captureStackTrace(this, this.constructor);
+      }
+    };
+  }
+});
 
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  CollectionsClient: () => CollectionsClient,
-  CollectionsError: () => CollectionsError
+// src/upload/platforms/common.ts
+function detectPlatform() {
+  if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
+    return "node";
+  }
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  return "unknown";
+}
+function normalizePath(p) {
+  return p.replace(/\\/g, "/");
+}
+function getExtension(filename) {
+  const lastDot = filename.lastIndexOf(".");
+  return lastDot === -1 ? "" : filename.slice(lastDot + 1).toLowerCase();
+}
+function getMimeType(filename) {
+  const ext = getExtension(filename);
+  const mimeTypes = {
+    // Images
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "png": "image/png",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "tif": "image/tiff",
+    "tiff": "image/tiff",
+    "bmp": "image/bmp",
+    "svg": "image/svg+xml",
+    // Documents
+    "pdf": "application/pdf",
+    "txt": "text/plain",
+    "json": "application/json",
+    "xml": "application/xml",
+    "html": "text/html",
+    "htm": "text/html",
+    "css": "text/css",
+    "js": "application/javascript",
+    // Archives
+    "zip": "application/zip",
+    "tar": "application/x-tar",
+    "gz": "application/gzip",
+    // Audio
+    "mp3": "audio/mpeg",
+    "wav": "audio/wav",
+    "ogg": "audio/ogg",
+    // Video
+    "mp4": "video/mp4",
+    "webm": "video/webm",
+    "mov": "video/quicktime"
+  };
+  return mimeTypes[ext] || "application/octet-stream";
+}
+var init_common = __esm({
+  "src/upload/platforms/common.ts"() {
+    "use strict";
+  }
+});
+
+// src/upload/lib/validation.ts
+function validateFileSize(size) {
+  if (size <= 0) {
+    throw new ValidationError("File size must be greater than 0");
+  }
+  if (size > MAX_FILE_SIZE) {
+    throw new ValidationError(
+      `File size (${formatBytes(size)}) exceeds maximum allowed size (${formatBytes(MAX_FILE_SIZE)})`
+    );
+  }
+}
+function validateBatchSize(totalSize) {
+  if (totalSize > MAX_BATCH_SIZE) {
+    throw new ValidationError(
+      `Total batch size (${formatBytes(totalSize)}) exceeds maximum allowed size (${formatBytes(MAX_BATCH_SIZE)})`
+    );
+  }
+}
+function validateLogicalPath(path2) {
+  if (!path2.startsWith("/")) {
+    throw new ValidationError("Logical path must start with /", "path");
+  }
+  if (INVALID_PATH_CHARS.test(path2)) {
+    throw new ValidationError(
+      "Logical path contains invalid characters",
+      "path"
+    );
+  }
+  const segments = path2.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0 && path2 !== "/") {
+    throw new ValidationError("Logical path cannot be empty", "path");
+  }
+  for (const segment of segments) {
+    if (segment === "." || segment === "..") {
+      throw new ValidationError(
+        "Logical path cannot contain . or .. segments",
+        "path"
+      );
+    }
+  }
+}
+function validateRefJson(content, fileName, logger) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new ValidationError(
+      `Invalid JSON in ${fileName}: ${error.message}`,
+      "ref"
+    );
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
+    throw new ValidationError(
+      `${fileName} must contain a JSON object`,
+      "ref"
+    );
+  }
+  if (!parsed.url || typeof parsed.url !== "string") {
+    throw new ValidationError(
+      `${fileName} must contain a 'url' field with a string value`,
+      "ref"
+    );
+  }
+  try {
+    const url = new URL(parsed.url);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error("URL must use HTTP or HTTPS protocol");
+    }
+  } catch (error) {
+    throw new ValidationError(
+      `Invalid URL in ${fileName}: ${error.message}`,
+      "ref"
+    );
+  }
+  if (!parsed.type) {
+    if (logger) {
+      logger.warn(`${fileName}: Missing 'type' field (optional but recommended)`);
+    }
+  }
+  if (parsed.type && OCR_PROCESSABLE_TYPES.includes(parsed.type)) {
+    const typeToExt = {
+      "image/jpeg": ".jpg",
+      "image/png": ".png",
+      "image/webp": ".webp"
+    };
+    const expectedExt = typeToExt[parsed.type];
+    if (expectedExt && !fileName.includes(`${expectedExt}.ref.json`)) {
+      if (logger) {
+        logger.warn(
+          `${fileName}: Type is '${parsed.type}' but filename doesn't include '${expectedExt}.ref.json' pattern. This file may not be processed by OCR. Consider renaming to include the extension (e.g., 'photo${expectedExt}.ref.json').`
+        );
+      }
+    }
+  }
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+}
+function validateCustomPrompts(prompts) {
+  if (!prompts) return;
+  const MAX_LENGTH = 5e4;
+  const MAX_TOTAL_LENGTH = 75e3;
+  const fields = [
+    "general",
+    "reorganization",
+    "pinax",
+    "description",
+    "cheimarros"
+  ];
+  let totalLength = 0;
+  for (const field of fields) {
+    const value = prompts[field];
+    if (value) {
+      if (value.length > MAX_LENGTH) {
+        throw new ValidationError(
+          `Custom prompt '${field}' exceeds maximum length of ${MAX_LENGTH} characters (current: ${value.length})`,
+          "customPrompts"
+        );
+      }
+      totalLength += value.length;
+    }
+  }
+  if (totalLength > MAX_TOTAL_LENGTH) {
+    throw new ValidationError(
+      `Total custom prompts length (${totalLength}) exceeds maximum of ${MAX_TOTAL_LENGTH} characters`,
+      "customPrompts"
+    );
+  }
+}
+function validateCustomPromptsLocation(processingConfig) {
+  if (!processingConfig) return;
+  if ("customPrompts" in processingConfig) {
+    throw new ValidationError(
+      "customPrompts must be a top-level field in UploaderConfig, not inside the processing config. Use: new ArkeUploader({ customPrompts: {...}, processing: {...} }) NOT: new ArkeUploader({ processing: { customPrompts: {...} } })",
+      "processing"
+    );
+  }
+}
+var MAX_FILE_SIZE, MAX_BATCH_SIZE, INVALID_PATH_CHARS, OCR_PROCESSABLE_TYPES;
+var init_validation = __esm({
+  "src/upload/lib/validation.ts"() {
+    "use strict";
+    init_errors();
+    MAX_FILE_SIZE = 5 * 1024 * 1024 * 1024;
+    MAX_BATCH_SIZE = 100 * 1024 * 1024 * 1024;
+    INVALID_PATH_CHARS = /[<>:"|?*\x00-\x1f]/;
+    OCR_PROCESSABLE_TYPES = [
+      "image/jpeg",
+      "image/png",
+      "image/webp"
+    ];
+  }
+});
+
+// src/upload/utils/hash.ts
+import { CID } from "multiformats/cid";
+import * as raw from "multiformats/codecs/raw";
+import { sha256 } from "multiformats/hashes/sha2";
+async function computeFileCID(filePath) {
+  const fs2 = await import("fs/promises");
+  try {
+    const fileBuffer = await fs2.readFile(filePath);
+    const hash = await sha256.digest(fileBuffer);
+    const cid = CID.create(1, raw.code, hash);
+    return cid.toString();
+  } catch (error) {
+    throw new Error(`CID computation failed: ${error.message}`);
+  }
+}
+async function computeCIDFromBuffer(data) {
+  const hash = await sha256.digest(data);
+  const cid = CID.create(1, raw.code, hash);
+  return cid.toString();
+}
+var init_hash = __esm({
+  "src/upload/utils/hash.ts"() {
+    "use strict";
+  }
+});
+
+// src/upload/types/processing.ts
+var DEFAULT_PROCESSING_CONFIG;
+var init_processing = __esm({
+  "src/upload/types/processing.ts"() {
+    "use strict";
+    DEFAULT_PROCESSING_CONFIG = {
+      ocr: true,
+      describe: true,
+      pinax: true
+    };
+  }
+});
+
+// src/upload/platforms/node.ts
+var node_exports = {};
+__export(node_exports, {
+  NodeScanner: () => NodeScanner
+});
+import fs from "fs/promises";
+import path from "path";
+var NodeScanner;
+var init_node = __esm({
+  "src/upload/platforms/node.ts"() {
+    "use strict";
+    init_errors();
+    init_validation();
+    init_hash();
+    init_processing();
+    init_common();
+    NodeScanner = class {
+      /**
+       * Scan directory recursively and collect file metadata
+       */
+      async scanFiles(source, options) {
+        const dirPath = Array.isArray(source) ? source[0] : source;
+        if (!dirPath || typeof dirPath !== "string") {
+          throw new ScanError("Node.js scanner requires a directory path", "");
+        }
+        const files = [];
+        try {
+          const stats = await fs.stat(dirPath);
+          if (!stats.isDirectory()) {
+            throw new ScanError(`Path is not a directory: ${dirPath}`, dirPath);
+          }
+        } catch (error) {
+          if (error.code === "ENOENT") {
+            throw new ScanError(`Directory not found: ${dirPath}`, dirPath);
+          }
+          throw new ScanError(`Cannot access directory: ${error.message}`, dirPath);
+        }
+        validateLogicalPath(options.rootPath);
+        const globalProcessingConfig = options.defaultProcessingConfig || DEFAULT_PROCESSING_CONFIG;
+        async function loadDirectoryProcessingConfig(dirPath2) {
+          const configPath = path.join(dirPath2, ".arke-process.json");
+          try {
+            const content = await fs.readFile(configPath, "utf-8");
+            return JSON.parse(content);
+          } catch (error) {
+            if (error.code !== "ENOENT") {
+              console.warn(`Error reading processing config ${configPath}: ${error.message}`);
+            }
+            return null;
+          }
+        }
+        function mergeProcessingConfig(defaults, override) {
+          if (!override) return defaults;
+          return {
+            ocr: override.ocr ?? defaults.ocr,
+            describe: override.describe ?? defaults.describe,
+            pinax: override.pinax ?? defaults.pinax
+          };
+        }
+        async function walk(currentPath, relativePath = "") {
+          const dirConfigOverride = await loadDirectoryProcessingConfig(currentPath);
+          const currentProcessingConfig = mergeProcessingConfig(
+            globalProcessingConfig,
+            dirConfigOverride
+          );
+          let entries;
+          try {
+            entries = await fs.readdir(currentPath, { withFileTypes: true });
+          } catch (error) {
+            console.warn(`Cannot read directory: ${currentPath}`, error.message);
+            return;
+          }
+          for (const entry of entries) {
+            const fullPath = path.join(currentPath, entry.name);
+            const relPath = path.join(relativePath, entry.name);
+            try {
+              if (entry.isSymbolicLink()) {
+                if (!options.followSymlinks) {
+                  continue;
+                }
+                const stats = await fs.stat(fullPath);
+                if (stats.isDirectory()) {
+                  await walk(fullPath, relPath);
+                } else if (stats.isFile()) {
+                  await processFile(fullPath, relPath, stats.size, currentProcessingConfig);
+                }
+                continue;
+              }
+              if (entry.isDirectory()) {
+                await walk(fullPath, relPath);
+                continue;
+              }
+              if (entry.isFile()) {
+                const stats = await fs.stat(fullPath);
+                await processFile(fullPath, relPath, stats.size, currentProcessingConfig);
+              }
+            } catch (error) {
+              if (error instanceof ScanError && error.message.includes(".ref.json")) {
+                throw error;
+              }
+              console.warn(`Error processing ${fullPath}: ${error.message}`);
+              continue;
+            }
+          }
+        }
+        async function processFile(fullPath, relativePath, size, processingConfig) {
+          const fileName = path.basename(fullPath);
+          if (fileName === ".arke-process.json") {
+            return;
+          }
+          if (fileName.endsWith(".ref.json")) {
+            try {
+              const content = await fs.readFile(fullPath, "utf-8");
+              validateRefJson(content, fileName, console);
+            } catch (error) {
+              throw new ScanError(
+                `Invalid .ref.json file: ${fileName} - ${error.message}`,
+                fullPath
+              );
+            }
+          }
+          try {
+            validateFileSize(size);
+          } catch (error) {
+            console.warn(`Skipping file that exceeds size limit: ${fileName}`, error.message);
+            return;
+          }
+          const normalizedRelPath = normalizePath(relativePath);
+          const logicalPath = path.posix.join(options.rootPath, normalizedRelPath);
+          try {
+            validateLogicalPath(logicalPath);
+          } catch (error) {
+            console.warn(`Skipping file with invalid logical path: ${logicalPath}`, error.message);
+            return;
+          }
+          const contentType = getMimeType(fileName);
+          try {
+            await fs.access(fullPath, fs.constants.R_OK);
+          } catch (error) {
+            console.warn(`Skipping unreadable file: ${fullPath}`);
+            return;
+          }
+          let cid;
+          try {
+            cid = await computeFileCID(fullPath);
+          } catch (error) {
+            console.warn(`Warning: CID computation failed for ${fullPath}, continuing without CID:`, error.message);
+            cid = void 0;
+          }
+          files.push({
+            localPath: fullPath,
+            logicalPath,
+            fileName,
+            size,
+            contentType,
+            cid,
+            processingConfig
+          });
+        }
+        await walk(dirPath);
+        files.sort((a, b) => a.size - b.size);
+        return files;
+      }
+      /**
+       * Read file contents as ArrayBuffer
+       */
+      async readFile(file) {
+        const buffer = await fs.readFile(file.localPath);
+        return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+      }
+    };
+  }
+});
+
+// src/upload/platforms/browser.ts
+var browser_exports = {};
+__export(browser_exports, {
+  BrowserScanner: () => BrowserScanner
+});
+var BrowserScanner;
+var init_browser = __esm({
+  "src/upload/platforms/browser.ts"() {
+    "use strict";
+    init_errors();
+    init_validation();
+    init_hash();
+    init_processing();
+    init_common();
+    BrowserScanner = class {
+      /**
+       * Scan files from File or FileList
+       */
+      async scanFiles(source, options) {
+        const fileList = Array.isArray(source) ? source : [source];
+        if (fileList.length === 0) {
+          throw new ScanError("No files provided", "");
+        }
+        validateLogicalPath(options.rootPath);
+        const globalProcessingConfig = options.defaultProcessingConfig || DEFAULT_PROCESSING_CONFIG;
+        const files = [];
+        for (const file of fileList) {
+          try {
+            const fileInfo = await this.processFile(file, options.rootPath, globalProcessingConfig);
+            if (fileInfo) {
+              files.push(fileInfo);
+            }
+          } catch (error) {
+            console.warn(`Error processing ${file.name}: ${error.message}`);
+            continue;
+          }
+        }
+        files.sort((a, b) => a.size - b.size);
+        return files;
+      }
+      /**
+       * Process a single File object
+       */
+      async processFile(file, rootPath, processingConfig) {
+        const fileName = file.name;
+        const size = file.size;
+        if (fileName.startsWith(".")) {
+          return null;
+        }
+        const skipFiles = ["Thumbs.db", "desktop.ini", "__MACOSX"];
+        if (skipFiles.includes(fileName)) {
+          return null;
+        }
+        if (fileName === ".arke-process.json") {
+          return null;
+        }
+        try {
+          validateFileSize(size);
+        } catch (error) {
+          console.warn(`Skipping file that exceeds size limit: ${fileName}`, error.message);
+          return null;
+        }
+        let relativePath = "";
+        if ("webkitRelativePath" in file && file.webkitRelativePath) {
+          const parts = file.webkitRelativePath.split("/");
+          if (parts.length > 1) {
+            relativePath = parts.slice(1).join("/");
+          } else {
+            relativePath = fileName;
+          }
+        } else {
+          relativePath = fileName;
+        }
+        const normalizedRelPath = normalizePath(relativePath);
+        const logicalPath = `${rootPath}/${normalizedRelPath}`.replace(/\/+/g, "/");
+        try {
+          validateLogicalPath(logicalPath);
+        } catch (error) {
+          console.warn(`Skipping file with invalid logical path: ${logicalPath}`, error.message);
+          return null;
+        }
+        const contentType = file.type || getMimeType(fileName);
+        let cid;
+        try {
+          const buffer = await file.arrayBuffer();
+          cid = await computeCIDFromBuffer(new Uint8Array(buffer));
+        } catch (error) {
+          console.warn(`Warning: CID computation failed for ${fileName}, continuing without CID:`, error.message);
+          cid = void 0;
+        }
+        return {
+          localPath: `__browser_file__${fileName}`,
+          // Special marker for browser files
+          logicalPath,
+          fileName,
+          size,
+          contentType,
+          cid,
+          processingConfig
+        };
+      }
+      /**
+       * Read file contents as ArrayBuffer
+       * Note: In browser context, the File object should be passed directly
+       */
+      async readFile(file) {
+        throw new Error("Browser scanner requires File objects to be provided directly during upload");
+      }
+    };
+  }
 });
-module.exports = __toCommonJS(src_exports);
 
 // src/collections/errors.ts
 var CollectionsError = class extends Error {
-  constructor(message, code = "UNKNOWN_ERROR", details) {
+  constructor(message, code2 = "UNKNOWN_ERROR", details) {
     super(message);
-    this.code = code;
+    this.code = code2;
     this.details = details;
     this.name = "CollectionsError";
   }
@@ -48,8 +643,8 @@ var CollectionsClient = class {
   // ---------------------------------------------------------------------------
   // Request helpers
   // ---------------------------------------------------------------------------
-  buildUrl(path, query) {
-    const url = new URL(`${this.baseUrl}${path}`);
+  buildUrl(path2, query) {
+    const url = new URL(`${this.baseUrl}${path2}`);
     if (query) {
       Object.entries(query).forEach(([key, value]) => {
         if (value !== void 0 && value !== null) {
@@ -71,9 +666,9 @@ var CollectionsClient = class {
     }
     return headers;
   }
-  async request(path, options = {}) {
+  async request(path2, options = {}) {
     const authRequired = options.authRequired ?? false;
-    const url = this.buildUrl(path, options.query);
+    const url = this.buildUrl(path2, options.query);
     const headers = new Headers(this.getHeaders(authRequired));
     if (options.headers) {
       Object.entries(options.headers).forEach(([k, v]) => {
@@ -92,10 +687,11 @@ var CollectionsClient = class {
       return await response.text();
     }
     let body;
+    const text = await response.text();
     try {
-      body = await response.json();
+      body = JSON.parse(text);
     } catch {
-      body = await response.text();
+      body = text;
     }
     const message = body?.error && typeof body.error === "string" ? body.error : `Request failed with status ${response.status}`;
     throw new CollectionsError(message, "HTTP_ERROR", {
@@ -224,9 +820,2885 @@ var CollectionsClient = class {
     return this.request(`/pi/${pi}/permissions`, { method: "GET" });
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  CollectionsClient,
-  CollectionsError
-});
+
+// src/upload/lib/worker-client-fetch.ts
+init_errors();
+
+// src/upload/utils/retry.ts
+init_errors();
+var DEFAULT_OPTIONS = {
+  maxRetries: 3,
+  initialDelay: 1e3,
+  // 1 second
+  maxDelay: 3e4,
+  // 30 seconds
+  shouldRetry: isRetryableError,
+  jitter: true
+};
+async function retryWithBackoff(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= opts.maxRetries) {
+        throw error;
+      }
+      if (opts.shouldRetry && !opts.shouldRetry(error)) {
+        throw error;
+      }
+      let delay;
+      if (error.statusCode === 429 && error.retryAfter) {
+        delay = Math.min(error.retryAfter * 1e3, opts.maxDelay);
+      } else {
+        delay = Math.min(
+          opts.initialDelay * Math.pow(2, attempt),
+          opts.maxDelay
+        );
+      }
+      if (opts.jitter) {
+        const jitterAmount = delay * 0.25;
+        delay = delay + (Math.random() * jitterAmount * 2 - jitterAmount);
+      }
+      await sleep(Math.floor(delay));
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/upload/lib/worker-client-fetch.ts
+var WorkerClient = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.authToken = config.authToken;
+    this.timeout = config.timeout ?? 3e4;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryInitialDelay = config.retryInitialDelay ?? 1e3;
+    this.retryMaxDelay = config.retryMaxDelay ?? 3e4;
+    this.retryJitter = config.retryJitter ?? true;
+    this.debug = config.debug ?? false;
+  }
+  setAuthToken(token) {
+    this.authToken = token;
+  }
+  /**
+   * Make HTTP request with fetch
+   */
+  async request(method, path2, body) {
+    const url = `${this.baseUrl}${path2}`;
+    if (this.debug) {
+      console.log(`HTTP Request: ${method} ${url}`, body);
+    }
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.authToken) {
+        headers["Authorization"] = `Bearer ${this.authToken}`;
+      }
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (this.debug) {
+        console.log(`HTTP Response: ${response.status}`, data);
+      }
+      if (!response.ok) {
+        const errorData = data;
+        throw new WorkerAPIError(
+          errorData.error || "Request failed",
+          response.status,
+          errorData.details
+        );
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof WorkerAPIError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new NetworkError(`Request timeout after ${this.timeout}ms`);
+      }
+      throw new NetworkError(`Network request failed: ${error.message}`);
+    }
+  }
+  /**
+   * Initialize a new batch upload
+   */
+  async initBatch(params) {
+    return retryWithBackoff(
+      () => this.request("POST", "/ingest/batches/init", params),
+      {
+        maxRetries: this.maxRetries,
+        initialDelay: this.retryInitialDelay,
+        maxDelay: this.retryMaxDelay,
+        jitter: this.retryJitter
+      }
+    );
+  }
+  /**
+   * Request presigned URLs for a file upload
+   */
+  async startFileUpload(batchId, params) {
+    return retryWithBackoff(
+      () => this.request(
+        "POST",
+        `/ingest/batches/${batchId}/files/start`,
+        params
+      ),
+      {
+        maxRetries: this.maxRetries,
+        initialDelay: this.retryInitialDelay,
+        maxDelay: this.retryMaxDelay,
+        jitter: this.retryJitter
+      }
+    );
+  }
+  /**
+   * Mark a file upload as complete
+   */
+  async completeFileUpload(batchId, params) {
+    return retryWithBackoff(
+      () => this.request(
+        "POST",
+        `/ingest/batches/${batchId}/files/complete`,
+        params
+      ),
+      {
+        maxRetries: this.maxRetries,
+        initialDelay: this.retryInitialDelay,
+        maxDelay: this.retryMaxDelay,
+        jitter: this.retryJitter
+      }
+    );
+  }
+  /**
+   * Finalize the batch after all files are uploaded
+   * Returns root_pi immediately for small batches, or status='discovery' for large batches
+   */
+  async finalizeBatch(batchId) {
+    return retryWithBackoff(
+      () => this.request(
+        "POST",
+        `/ingest/batches/${batchId}/finalize`,
+        {}
+      ),
+      {
+        maxRetries: this.maxRetries,
+        initialDelay: this.retryInitialDelay,
+        maxDelay: this.retryMaxDelay,
+        jitter: this.retryJitter
+      }
+    );
+  }
+  /**
+   * Get current batch status (used for polling during async discovery)
+   */
+  async getBatchStatus(batchId) {
+    return retryWithBackoff(
+      () => this.request(
+        "GET",
+        `/ingest/batches/${batchId}/status`
+      ),
+      {
+        maxRetries: this.maxRetries,
+        initialDelay: this.retryInitialDelay,
+        maxDelay: this.retryMaxDelay,
+        jitter: this.retryJitter
+      }
+    );
+  }
+};
+
+// src/upload/uploader.ts
+init_common();
+
+// src/upload/lib/simple-fetch.ts
+init_errors();
+async function uploadSimple(fileData, presignedUrl, contentType, options = {}) {
+  const { maxRetries = 3, retryInitialDelay, retryMaxDelay, retryJitter } = options;
+  await retryWithBackoff(
+    async () => {
+      let response;
+      try {
+        response = await fetch(presignedUrl, {
+          method: "PUT",
+          body: fileData,
+          headers: {
+            ...contentType ? { "Content-Type": contentType } : {}
+          }
+        });
+      } catch (error) {
+        throw new UploadError(`Upload failed: ${error.message}`, void 0, void 0, error);
+      }
+      if (!response.ok) {
+        const retryAfter = response.headers.get("retry-after");
+        const error = new UploadError(
+          `Upload failed with status ${response.status}: ${response.statusText}`,
+          void 0,
+          response.status
+        );
+        if (retryAfter && response.status === 429) {
+          error.retryAfter = parseInt(retryAfter, 10);
+        }
+        throw error;
+      }
+    },
+    {
+      maxRetries,
+      initialDelay: retryInitialDelay,
+      maxDelay: retryMaxDelay,
+      jitter: retryJitter
+    }
+  );
+}
+
+// src/upload/lib/multipart-fetch.ts
+init_errors();
+var DEFAULT_PART_SIZE = 10 * 1024 * 1024;
+async function uploadMultipart(fileData, presignedUrls, concurrency = 3, options = {}) {
+  const totalSize = fileData.byteLength;
+  const partSize = Math.ceil(totalSize / presignedUrls.length);
+  const parts = [];
+  const queue = [];
+  const { maxRetries = 3, retryInitialDelay, retryMaxDelay, retryJitter } = options;
+  for (let i = 0; i < presignedUrls.length; i++) {
+    const partNumber = i + 1;
+    const start = i * partSize;
+    const end = Math.min(start + partSize, totalSize);
+    const partData = fileData.slice(start, end);
+    const url = presignedUrls[i];
+    queue.push(async () => {
+      const etag = await uploadPart(partData, url, partNumber, maxRetries, {
+        initialDelay: retryInitialDelay,
+        maxDelay: retryMaxDelay,
+        jitter: retryJitter
+      });
+      parts.push({ part_number: partNumber, etag });
+    });
+  }
+  await executeWithConcurrency(queue, concurrency);
+  parts.sort((a, b) => a.part_number - b.part_number);
+  return parts;
+}
+async function uploadPart(partData, presignedUrl, partNumber, maxRetries = 3, retryOptions = {}) {
+  return retryWithBackoff(
+    async () => {
+      let response;
+      try {
+        response = await fetch(presignedUrl, {
+          method: "PUT",
+          body: partData
+        });
+      } catch (error) {
+        throw new UploadError(
+          `Part ${partNumber} upload failed: ${error.message}`,
+          void 0,
+          void 0,
+          error
+        );
+      }
+      if (!response.ok) {
+        const retryAfter = response.headers.get("retry-after");
+        const error = new UploadError(
+          `Part ${partNumber} upload failed with status ${response.status}: ${response.statusText}`,
+          void 0,
+          response.status
+        );
+        if (retryAfter && response.status === 429) {
+          error.retryAfter = parseInt(retryAfter, 10);
+        }
+        throw error;
+      }
+      const etag = response.headers.get("etag");
+      if (!etag) {
+        throw new UploadError(
+          `Part ${partNumber} upload succeeded but no ETag returned`,
+          void 0,
+          response.status
+        );
+      }
+      return etag.replace(/"/g, "");
+    },
+    {
+      maxRetries,
+      initialDelay: retryOptions.initialDelay,
+      maxDelay: retryOptions.maxDelay,
+      jitter: retryOptions.jitter
+    }
+  );
+}
+async function executeWithConcurrency(tasks, concurrency) {
+  const queue = [...tasks];
+  const workers = [];
+  const processNext = async () => {
+    while (queue.length > 0) {
+      const task = queue.shift();
+      await task();
+    }
+  };
+  for (let i = 0; i < Math.min(concurrency, tasks.length); i++) {
+    workers.push(processNext());
+  }
+  await Promise.all(workers);
+}
+
+// src/upload/uploader.ts
+init_errors();
+init_validation();
+var MULTIPART_THRESHOLD = 5 * 1024 * 1024;
+var ArkeUploader = class {
+  constructor(config) {
+    this.scanner = null;
+    validateCustomPromptsLocation(config.processing);
+    this.config = {
+      rootPath: "/uploads",
+      // Must have at least one segment (not just '/')
+      parallelUploads: 5,
+      parallelParts: 3,
+      ...config
+    };
+    this.workerClient = new WorkerClient({
+      baseUrl: config.gatewayUrl,
+      authToken: config.authToken,
+      timeout: config.timeout,
+      maxRetries: config.maxRetries,
+      retryInitialDelay: config.retryInitialDelay,
+      retryMaxDelay: config.retryMaxDelay,
+      retryJitter: config.retryJitter,
+      debug: false
+    });
+    this.platform = detectPlatform();
+  }
+  /**
+   * Get platform-specific scanner
+   */
+  async getScanner() {
+    if (this.scanner) {
+      return this.scanner;
+    }
+    if (this.platform === "node") {
+      const { NodeScanner: NodeScanner2 } = await Promise.resolve().then(() => (init_node(), node_exports));
+      this.scanner = new NodeScanner2();
+    } else if (this.platform === "browser") {
+      const { BrowserScanner: BrowserScanner2 } = await Promise.resolve().then(() => (init_browser(), browser_exports));
+      this.scanner = new BrowserScanner2();
+    } else {
+      throw new ValidationError("Unsupported platform");
+    }
+    return this.scanner;
+  }
+  /**
+   * Upload a batch of files
+   * @param source - Directory path (Node.js) or File[]/FileList (browser)
+   * @param options - Upload options
+   */
+  async uploadBatch(source, options = {}) {
+    const startTime = Date.now();
+    const { onProgress, dryRun = false } = options;
+    this.reportProgress(onProgress, {
+      phase: "scanning",
+      filesTotal: 0,
+      filesUploaded: 0,
+      bytesTotal: 0,
+      bytesUploaded: 0,
+      percentComplete: 0
+    });
+    const scanner = await this.getScanner();
+    const files = await scanner.scanFiles(source, {
+      rootPath: this.config.rootPath || "/",
+      followSymlinks: true,
+      defaultProcessingConfig: this.config.processing
+    });
+    if (files.length === 0) {
+      throw new ValidationError("No files found to upload");
+    }
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+    validateBatchSize(totalSize);
+    if (this.config.customPrompts) {
+      validateCustomPrompts(this.config.customPrompts);
+      const promptFields = Object.keys(this.config.customPrompts).filter(
+        (key) => this.config.customPrompts[key]
+      );
+      console.log(`[Arke Upload SDK] Custom prompts configured: ${promptFields.join(", ")}`);
+    }
+    if (dryRun) {
+      return {
+        batchId: "dry-run",
+        rootPi: "dry-run",
+        filesUploaded: files.length,
+        bytesUploaded: totalSize,
+        durationMs: Date.now() - startTime
+      };
+    }
+    const { batch_id } = await this.workerClient.initBatch({
+      uploader: this.config.uploader,
+      root_path: this.config.rootPath || "/",
+      parent_pi: this.config.parentPi || "",
+      metadata: this.config.metadata,
+      file_count: files.length,
+      total_size: totalSize,
+      custom_prompts: this.config.customPrompts
+    });
+    if (this.config.customPrompts) {
+      console.log(`[Arke Upload SDK] Custom prompts sent to worker for batch ${batch_id}`);
+    }
+    this.reportProgress(onProgress, {
+      phase: "uploading",
+      filesTotal: files.length,
+      filesUploaded: 0,
+      bytesTotal: totalSize,
+      bytesUploaded: 0,
+      percentComplete: 0
+    });
+    let filesUploaded = 0;
+    let bytesUploaded = 0;
+    const { failedFiles } = await this.uploadFilesWithConcurrency(
+      batch_id,
+      files,
+      source,
+      this.config.parallelUploads || 5,
+      (file, bytes) => {
+        filesUploaded++;
+        bytesUploaded += bytes;
+        this.reportProgress(onProgress, {
+          phase: "uploading",
+          filesTotal: files.length,
+          filesUploaded,
+          bytesTotal: totalSize,
+          bytesUploaded,
+          currentFile: file.fileName,
+          percentComplete: Math.round(bytesUploaded / totalSize * 100)
+        });
+      }
+    );
+    if (failedFiles.length === files.length) {
+      throw new ValidationError(
+        `All ${files.length} files failed to upload. First error: ${failedFiles[0]?.error || "Unknown"}`
+      );
+    }
+    if (failedFiles.length > 0) {
+      console.warn(
+        `Warning: ${failedFiles.length} of ${files.length} files failed to upload:`,
+        failedFiles.map((f) => `${f.file.fileName}: ${f.error}`).join(", ")
+      );
+    }
+    this.reportProgress(onProgress, {
+      phase: "finalizing",
+      filesTotal: files.length,
+      filesUploaded,
+      bytesTotal: totalSize,
+      bytesUploaded,
+      percentComplete: 95
+    });
+    const finalizeResult = await this.workerClient.finalizeBatch(batch_id);
+    let rootPi;
+    if (finalizeResult.root_pi) {
+      rootPi = finalizeResult.root_pi;
+    } else if (finalizeResult.status === "discovery") {
+      this.reportProgress(onProgress, {
+        phase: "discovery",
+        filesTotal: files.length,
+        filesUploaded,
+        bytesTotal: totalSize,
+        bytesUploaded,
+        percentComplete: 97
+      });
+      rootPi = await this.pollForRootPi(batch_id, onProgress, files.length, totalSize, bytesUploaded);
+    } else {
+      throw new ValidationError(
+        `Finalization returned unexpected status: ${finalizeResult.status} without root_pi`
+      );
+    }
+    this.reportProgress(onProgress, {
+      phase: "complete",
+      filesTotal: files.length,
+      filesUploaded,
+      bytesTotal: totalSize,
+      bytesUploaded,
+      percentComplete: 100
+    });
+    return {
+      batchId: batch_id,
+      rootPi,
+      filesUploaded,
+      bytesUploaded,
+      durationMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Poll for root_pi during async discovery
+   */
+  async pollForRootPi(batchId, onProgress, filesTotal, bytesTotal, bytesUploaded) {
+    const POLL_INTERVAL_MS = 2e3;
+    const MAX_POLL_TIME_MS = 30 * 60 * 1e3;
+    const startTime = Date.now();
+    while (Date.now() - startTime < MAX_POLL_TIME_MS) {
+      const status = await this.workerClient.getBatchStatus(batchId);
+      if (status.root_pi) {
+        return status.root_pi;
+      }
+      if (status.status === "failed") {
+        throw new ValidationError(`Batch discovery failed`);
+      }
+      if (status.discovery_progress && onProgress) {
+        const { total, published } = status.discovery_progress;
+        const discoveryPercent = total > 0 ? Math.round(published / total * 100) : 0;
+        this.reportProgress(onProgress, {
+          phase: "discovery",
+          filesTotal,
+          filesUploaded: filesTotal,
+          bytesTotal,
+          bytesUploaded,
+          percentComplete: 95 + Math.round(discoveryPercent * 0.04)
+          // 95-99%
+        });
+      }
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    throw new ValidationError(`Discovery timed out after ${MAX_POLL_TIME_MS / 1e3} seconds`);
+  }
+  /**
+   * Upload files with controlled concurrency
+   */
+  async uploadFilesWithConcurrency(batchId, files, source, concurrency, onFileComplete) {
+    const queue = [...files];
+    const workers = [];
+    const failedFiles = [];
+    const processNext = async () => {
+      while (queue.length > 0) {
+        const file = queue.shift();
+        try {
+          await this.uploadSingleFile(batchId, file, source);
+          onFileComplete(file, file.size);
+        } catch (error) {
+          const errorMessage = error.message || "Unknown error";
+          console.error(`Failed to upload ${file.fileName}: ${errorMessage}`);
+          failedFiles.push({ file, error: errorMessage });
+        }
+      }
+    };
+    for (let i = 0; i < Math.min(concurrency, files.length); i++) {
+      workers.push(processNext());
+    }
+    await Promise.all(workers);
+    return { failedFiles };
+  }
+  /**
+   * Upload a single file
+   */
+  async uploadSingleFile(batchId, file, source) {
+    const uploadInfo = await this.workerClient.startFileUpload(batchId, {
+      file_name: file.fileName,
+      file_size: file.size,
+      logical_path: file.logicalPath,
+      content_type: file.contentType,
+      cid: file.cid,
+      processing_config: file.processingConfig
+    });
+    const fileData = await this.getFileData(file, source);
+    const retryOptions = {
+      maxRetries: this.config.maxRetries,
+      retryInitialDelay: this.config.retryInitialDelay,
+      retryMaxDelay: this.config.retryMaxDelay,
+      retryJitter: this.config.retryJitter
+    };
+    if (uploadInfo.upload_type === "simple") {
+      await uploadSimple(fileData, uploadInfo.presigned_url, file.contentType, retryOptions);
+    } else {
+      const partUrls = uploadInfo.presigned_urls.map((p) => p.url);
+      const parts = await uploadMultipart(
+        fileData,
+        partUrls,
+        this.config.parallelParts || 3,
+        retryOptions
+      );
+      await this.workerClient.completeFileUpload(batchId, {
+        r2_key: uploadInfo.r2_key,
+        upload_id: uploadInfo.upload_id,
+        parts
+      });
+      return;
+    }
+    await this.workerClient.completeFileUpload(batchId, {
+      r2_key: uploadInfo.r2_key
+    });
+  }
+  /**
+   * Get file data based on platform
+   */
+  async getFileData(file, source) {
+    if (this.platform === "node") {
+      const fs2 = await import("fs/promises");
+      const buffer = await fs2.readFile(file.localPath);
+      return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    } else if (this.platform === "browser") {
+      const files = Array.isArray(source) ? source : [source];
+      const browserFile = files.find(
+        (f) => f instanceof File && f.name === file.fileName
+      );
+      if (!browserFile) {
+        throw new Error(`Could not find browser File object for ${file.fileName}`);
+      }
+      return browserFile.arrayBuffer();
+    }
+    throw new Error("Unsupported platform for file reading");
+  }
+  /**
+   * Report progress to callback
+   */
+  reportProgress(callback, progress) {
+    if (callback) {
+      callback(progress);
+    }
+  }
+};
+
+// src/upload/client.ts
+function getUserIdFromToken(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    let decoded;
+    if (typeof atob === "function") {
+      decoded = atob(payload);
+    } else {
+      decoded = Buffer.from(payload, "base64").toString("utf-8");
+    }
+    const data = JSON.parse(decoded);
+    return data.sub || null;
+  } catch {
+    return null;
+  }
+}
+var UploadClient = class {
+  constructor(config) {
+    const uploader = config.uploader || getUserIdFromToken(config.authToken) || "unknown";
+    this.config = { ...config, uploader };
+    this.collectionsClient = new CollectionsClient({
+      gatewayUrl: config.gatewayUrl,
+      authToken: config.authToken,
+      fetchImpl: config.fetchImpl
+    });
+  }
+  /**
+   * Update the auth token (e.g., after token refresh)
+   */
+  setAuthToken(token) {
+    this.config = { ...this.config, authToken: token };
+    this.collectionsClient.setAuthToken(token);
+  }
+  /**
+   * Create a new collection and upload files to it
+   *
+   * Anyone authenticated can create a new collection.
+   * The root PI of the uploaded files becomes the collection's root.
+   */
+  async createCollection(options) {
+    const { files, collectionMetadata, customPrompts, processing, onProgress, dryRun } = options;
+    const metadata = {
+      ...collectionMetadata,
+      visibility: collectionMetadata.visibility || "public"
+    };
+    const uploader = new ArkeUploader({
+      gatewayUrl: this.config.gatewayUrl,
+      authToken: this.config.authToken,
+      uploader: this.config.uploader,
+      customPrompts,
+      processing
+    });
+    const batchResult = await uploader.uploadBatch(files, {
+      onProgress,
+      dryRun
+    });
+    if (dryRun) {
+      return {
+        ...batchResult,
+        collection: {
+          id: "dry-run",
+          title: metadata.title,
+          slug: metadata.slug,
+          description: metadata.description,
+          visibility: metadata.visibility,
+          rootPi: "dry-run"
+        }
+      };
+    }
+    const collection = await this.collectionsClient.registerRoot({
+      ...metadata,
+      rootPi: batchResult.rootPi
+    });
+    return {
+      ...batchResult,
+      collection
+    };
+  }
+  /**
+   * Add files to an existing collection
+   *
+   * Requires owner or editor role on the collection containing the parent PI.
+   * Use this to add a folder or files to an existing collection hierarchy.
+   *
+   * Note: Permission checks are enforced server-side by the ingest worker.
+   * The server will return 403 if the user lacks edit access to the parent PI.
+   */
+  async addToCollection(options) {
+    const { files, parentPi, customPrompts, processing, onProgress, dryRun } = options;
+    const uploader = new ArkeUploader({
+      gatewayUrl: this.config.gatewayUrl,
+      authToken: this.config.authToken,
+      uploader: this.config.uploader,
+      parentPi,
+      customPrompts,
+      processing
+    });
+    return uploader.uploadBatch(files, {
+      onProgress,
+      dryRun
+    });
+  }
+  /**
+   * Check if you can edit a specific PI (i.e., add files to its collection)
+   */
+  async canEdit(pi) {
+    return this.collectionsClient.getPiPermissions(pi);
+  }
+  /**
+   * Get access to the underlying collections client for other operations
+   */
+  get collections() {
+    return this.collectionsClient;
+  }
+};
+
+// src/index.ts
+init_errors();
+
+// src/query/errors.ts
+var QueryError = class extends Error {
+  constructor(message, code2 = "UNKNOWN_ERROR", details) {
+    super(message);
+    this.code = code2;
+    this.details = details;
+    this.name = "QueryError";
+  }
+};
+
+// src/query/client.ts
+var QueryClient = class {
+  constructor(config) {
+    this.baseUrl = config.gatewayUrl.replace(/\/$/, "");
+    this.fetchImpl = config.fetchImpl ?? fetch;
+  }
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+  buildUrl(path2, query) {
+    const url = new URL(`${this.baseUrl}${path2}`);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+  async request(path2, options = {}) {
+    const url = this.buildUrl(path2, options.query);
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (options.headers) {
+      Object.entries(options.headers).forEach(([k, v]) => {
+        if (v !== void 0) headers.set(k, v);
+      });
+    }
+    const response = await this.fetchImpl(url, { ...options, headers });
+    if (response.ok) {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      return await response.text();
+    }
+    let body;
+    const text = await response.text();
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+    const message = body?.error && typeof body.error === "string" ? body.error : body?.message && typeof body.message === "string" ? body.message : `Request failed with status ${response.status}`;
+    throw new QueryError(message, "HTTP_ERROR", {
+      status: response.status,
+      body
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Query methods
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a path query against the knowledge graph.
+   *
+   * @param pathQuery - The path query string (e.g., '"alice austen" -[*]{,4}-> type:person')
+   * @param options - Query options (k, k_explore, lineage, enrich, etc.)
+   * @returns Query results with entities, paths, and metadata
+   *
+   * @example
+   * ```typescript
+   * // Simple semantic search
+   * const results = await query.path('"Washington" type:person');
+   *
+   * // Multi-hop traversal
+   * const results = await query.path('"alice austen" -[*]{,4}-> type:person ~ "photographer"');
+   *
+   * // With lineage filtering (collection scope)
+   * const results = await query.path('"letters" type:document', {
+   *   lineage: { sourcePi: 'arke:my_collection', direction: 'descendants' },
+   *   k: 10,
+   * });
+   * ```
+   */
+  async path(pathQuery, options = {}) {
+    return this.request("/query/path", {
+      method: "POST",
+      body: JSON.stringify({
+        path: pathQuery,
+        ...options
+      })
+    });
+  }
+  /**
+   * Execute a natural language query.
+   *
+   * The query is translated to a path query using an LLM, then executed.
+   *
+   * @param question - Natural language question
+   * @param options - Query options including custom_instructions for the LLM
+   * @returns Query results with translation info
+   *
+   * @example
+   * ```typescript
+   * const results = await query.natural('Find photographers connected to Alice Austen');
+   * console.log('Generated query:', results.translation.path);
+   * console.log('Explanation:', results.translation.explanation);
+   * ```
+   */
+  async natural(question, options = {}) {
+    const { custom_instructions, ...queryOptions } = options;
+    return this.request("/query/natural", {
+      method: "POST",
+      body: JSON.stringify({
+        query: question,
+        custom_instructions,
+        ...queryOptions
+      })
+    });
+  }
+  /**
+   * Translate a natural language question to a path query without executing it.
+   *
+   * Useful for understanding how questions are translated or for manual execution later.
+   *
+   * @param question - Natural language question
+   * @param customInstructions - Optional additional instructions for the LLM
+   * @returns Translation result with path query and explanation
+   *
+   * @example
+   * ```typescript
+   * const result = await query.translate('Who wrote letters from Philadelphia?');
+   * console.log('Path query:', result.path);
+   * // '"letters" <-[authored, wrote]- type:person -[located]-> "Philadelphia"'
+   * ```
+   */
+  async translate(question, customInstructions) {
+    return this.request("/query/translate", {
+      method: "POST",
+      body: JSON.stringify({
+        query: question,
+        custom_instructions: customInstructions
+      })
+    });
+  }
+  /**
+   * Parse and validate a path query without executing it.
+   *
+   * Returns the AST (Abstract Syntax Tree) if valid, or throws an error.
+   *
+   * @param pathQuery - The path query to parse
+   * @returns Parsed AST
+   * @throws QueryError if the query has syntax errors
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const result = await query.parse('"test" -[*]-> type:person');
+   *   console.log('Valid query, AST:', result.ast);
+   * } catch (err) {
+   *   console.error('Invalid query:', err.message);
+   * }
+   * ```
+   */
+  async parse(pathQuery) {
+    const url = this.buildUrl("/query/parse", { path: pathQuery });
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" }
+    });
+    const body = await response.json();
+    if ("error" in body && body.error === "Parse error") {
+      throw new QueryError(
+        body.message,
+        "PARSE_ERROR",
+        { position: body.position }
+      );
+    }
+    if (!response.ok) {
+      throw new QueryError(
+        body.error || `Request failed with status ${response.status}`,
+        "HTTP_ERROR",
+        { status: response.status, body }
+      );
+    }
+    return body;
+  }
+  /**
+   * Get the path query syntax documentation.
+   *
+   * Returns comprehensive documentation including entry points, edge traversal,
+   * filters, examples, and constraints.
+   *
+   * @returns Syntax documentation
+   *
+   * @example
+   * ```typescript
+   * const syntax = await query.syntax();
+   *
+   * // List all entry point types
+   * syntax.entryPoints.types.forEach(ep => {
+   *   console.log(`${ep.syntax} - ${ep.description}`);
+   * });
+   *
+   * // Show examples
+   * syntax.examples.forEach(ex => {
+   *   console.log(`${ex.description}: ${ex.query}`);
+   * });
+   * ```
+   */
+  async syntax() {
+    return this.request("/query/syntax", {
+      method: "GET"
+    });
+  }
+  /**
+   * Check the health of the query service.
+   *
+   * @returns Health status
+   */
+  async health() {
+    return this.request("/query/health", { method: "GET" });
+  }
+  /**
+   * Search for collections by semantic similarity.
+   *
+   * Searches the dedicated collections index for fast semantic matching.
+   *
+   * @param query - Search query text
+   * @param options - Search options (limit, visibility filter)
+   * @returns Matching collections with similarity scores
+   *
+   * @example
+   * ```typescript
+   * // Search for photography-related collections
+   * const results = await query.searchCollections('photography');
+   * console.log(results.collections[0].title);
+   *
+   * // Search only public collections
+   * const publicResults = await query.searchCollections('history', {
+   *   visibility: 'public',
+   *   limit: 20,
+   * });
+   * ```
+   */
+  async searchCollections(query, options = {}) {
+    return this.request("/query/search/collections", {
+      method: "GET",
+      query: {
+        q: query,
+        limit: options.limit?.toString(),
+        visibility: options.visibility
+      }
+    });
+  }
+};
+
+// src/edit/errors.ts
+var EditError = class extends Error {
+  constructor(message, code2 = "UNKNOWN_ERROR", details) {
+    super(message);
+    this.code = code2;
+    this.details = details;
+    this.name = "EditError";
+  }
+};
+var EntityNotFoundError = class extends EditError {
+  constructor(pi) {
+    super(`Entity not found: ${pi}`, "ENTITY_NOT_FOUND", { pi });
+    this.name = "EntityNotFoundError";
+  }
+};
+var CASConflictError = class extends EditError {
+  constructor(pi, expectedTip, actualTip) {
+    super(
+      `CAS conflict: entity ${pi} was modified (expected ${expectedTip}, got ${actualTip})`,
+      "CAS_CONFLICT",
+      { pi, expectedTip, actualTip }
+    );
+    this.name = "CASConflictError";
+  }
+};
+var ReprocessError = class extends EditError {
+  constructor(message, batchId) {
+    super(message, "REPROCESS_ERROR", { batchId });
+    this.name = "ReprocessError";
+  }
+};
+var ValidationError2 = class extends EditError {
+  constructor(message, field) {
+    super(message, "VALIDATION_ERROR", { field });
+    this.name = "ValidationError";
+  }
+};
+var PermissionError = class extends EditError {
+  constructor(message, pi) {
+    super(message, "PERMISSION_DENIED", { pi });
+    this.name = "PermissionError";
+  }
+};
+
+// src/edit/client.ts
+var DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 5,
+  initialDelayMs: 2e3,
+  // Start with 2s delay (orchestrator needs time to initialize)
+  maxDelayMs: 3e4,
+  // Cap at 30s
+  backoffMultiplier: 2
+  // Double each retry
+};
+var EditClient = class {
+  constructor(config) {
+    this.gatewayUrl = config.gatewayUrl.replace(/\/$/, "");
+    this.authToken = config.authToken;
+    this.statusUrlTransform = config.statusUrlTransform;
+  }
+  /**
+   * Update the auth token (useful for token refresh)
+   */
+  setAuthToken(token) {
+    this.authToken = token;
+  }
+  /**
+   * Sleep for a given number of milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Execute a fetch with exponential backoff retry on transient errors
+   */
+  async fetchWithRetry(url, options, retryOptions = DEFAULT_RETRY_OPTIONS) {
+    let lastError = null;
+    let delay = retryOptions.initialDelayMs;
+    for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+      try {
+        const response = await fetch(url, options);
+        if (response.status >= 500 && attempt < retryOptions.maxRetries) {
+          lastError = new Error(`Server error: ${response.status} ${response.statusText}`);
+          await this.sleep(delay);
+          delay = Math.min(delay * retryOptions.backoffMultiplier, retryOptions.maxDelayMs);
+          continue;
+        }
+        return response;
+      } catch (error) {
+        lastError = error;
+        if (attempt < retryOptions.maxRetries) {
+          await this.sleep(delay);
+          delay = Math.min(delay * retryOptions.backoffMultiplier, retryOptions.maxDelayMs);
+        }
+      }
+    }
+    throw lastError || new Error("Request failed after retries");
+  }
+  getHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    return headers;
+  }
+  /**
+   * Handle common error responses
+   */
+  handleErrorResponse(response, context) {
+    if (response.status === 403) {
+      throw new PermissionError(`Permission denied: ${context}`);
+    }
+    throw new EditError(
+      `${context}: ${response.statusText}`,
+      "API_ERROR",
+      { status: response.status }
+    );
+  }
+  // ===========================================================================
+  // IPFS Wrapper Operations (via /api/*)
+  // ===========================================================================
+  /**
+   * Fetch an entity by PI
+   */
+  async getEntity(pi) {
+    const response = await fetch(`${this.gatewayUrl}/api/entities/${pi}`, {
+      headers: this.getHeaders()
+    });
+    if (response.status === 404) {
+      throw new EntityNotFoundError(pi);
+    }
+    if (!response.ok) {
+      this.handleErrorResponse(response, `Failed to fetch entity ${pi}`);
+    }
+    return response.json();
+  }
+  /**
+   * Fetch content by CID
+   */
+  async getContent(cid) {
+    const response = await fetch(`${this.gatewayUrl}/api/cat/${cid}`, {
+      headers: this.getHeaders()
+    });
+    if (!response.ok) {
+      this.handleErrorResponse(response, `Failed to fetch content ${cid}`);
+    }
+    return response.text();
+  }
+  /**
+   * Upload content and get CID
+   */
+  async uploadContent(content, filename) {
+    const formData = new FormData();
+    const blob = new Blob([content], { type: "text/plain" });
+    formData.append("file", blob, filename);
+    const headers = {};
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    const response = await fetch(`${this.gatewayUrl}/api/upload`, {
+      method: "POST",
+      headers,
+      body: formData
+    });
+    if (!response.ok) {
+      this.handleErrorResponse(response, "Failed to upload content");
+    }
+    const result = await response.json();
+    return result[0].cid;
+  }
+  /**
+   * Update an entity with new components
+   */
+  async updateEntity(pi, update) {
+    const response = await fetch(`${this.gatewayUrl}/api/entities/${pi}/versions`, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: JSON.stringify({
+        expect_tip: update.expect_tip,
+        components: update.components,
+        components_remove: update.components_remove,
+        note: update.note
+      })
+    });
+    if (response.status === 409) {
+      const entity = await this.getEntity(pi);
+      throw new CASConflictError(
+        pi,
+        update.expect_tip,
+        entity.manifest_cid
+      );
+    }
+    if (!response.ok) {
+      this.handleErrorResponse(response, `Failed to update entity ${pi}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Reprocess API Operations (via /reprocess/*)
+  // ===========================================================================
+  /**
+   * Trigger reprocessing for an entity
+   */
+  async reprocess(request) {
+    const response = await fetch(`${this.gatewayUrl}/reprocess/reprocess`, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: JSON.stringify({
+        pi: request.pi,
+        phases: request.phases,
+        cascade: request.cascade,
+        options: request.options
+      })
+    });
+    if (response.status === 403) {
+      const error = await response.json().catch(() => ({}));
+      throw new PermissionError(
+        error.message || `Permission denied to reprocess ${request.pi}`,
+        request.pi
+      );
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new ReprocessError(
+        error.message || `Reprocess failed: ${response.statusText}`,
+        void 0
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Get reprocessing status by batch ID
+   *
+   * Uses exponential backoff retry to handle transient 500 errors
+   * that occur when the orchestrator is initializing.
+   *
+   * @param statusUrl - The status URL returned from reprocess()
+   * @param isFirstPoll - If true, uses a longer initial delay (orchestrator warmup)
+   */
+  async getReprocessStatus(statusUrl, isFirstPoll = false) {
+    const retryOptions = isFirstPoll ? { ...DEFAULT_RETRY_OPTIONS, initialDelayMs: 3e3 } : DEFAULT_RETRY_OPTIONS;
+    const fetchUrl = this.statusUrlTransform ? this.statusUrlTransform(statusUrl) : statusUrl;
+    const response = await this.fetchWithRetry(
+      fetchUrl,
+      { headers: this.getHeaders() },
+      retryOptions
+    );
+    if (!response.ok) {
+      throw new EditError(
+        `Failed to fetch reprocess status: ${response.statusText}`,
+        "STATUS_ERROR",
+        { status: response.status }
+      );
+    }
+    return response.json();
+  }
+};
+
+// src/edit/diff.ts
+import * as Diff from "diff";
+var DiffEngine = class {
+  /**
+   * Compute diff between two strings
+   */
+  static diff(original, modified) {
+    const changes = Diff.diffLines(original, modified);
+    const diffs = [];
+    let lineNumber = 1;
+    for (const change of changes) {
+      if (change.added) {
+        diffs.push({
+          type: "addition",
+          modified: change.value.trimEnd(),
+          lineNumber
+        });
+      } else if (change.removed) {
+        diffs.push({
+          type: "deletion",
+          original: change.value.trimEnd(),
+          lineNumber
+        });
+      } else {
+        const lines = change.value.split("\n").length - 1;
+        lineNumber += lines;
+      }
+      if (change.added) {
+        lineNumber += change.value.split("\n").length - 1;
+      }
+    }
+    return diffs;
+  }
+  /**
+   * Compute word-level diff for more granular changes
+   */
+  static diffWords(original, modified) {
+    const changes = Diff.diffWords(original, modified);
+    const diffs = [];
+    for (const change of changes) {
+      if (change.added) {
+        diffs.push({
+          type: "addition",
+          modified: change.value
+        });
+      } else if (change.removed) {
+        diffs.push({
+          type: "deletion",
+          original: change.value
+        });
+      }
+    }
+    return diffs;
+  }
+  /**
+   * Create a ComponentDiff from original and modified content
+   */
+  static createComponentDiff(componentName, original, modified) {
+    const diffs = this.diff(original, modified);
+    const hasChanges = diffs.length > 0;
+    let summary;
+    if (!hasChanges) {
+      summary = "No changes";
+    } else {
+      const additions = diffs.filter((d) => d.type === "addition").length;
+      const deletions = diffs.filter((d) => d.type === "deletion").length;
+      const parts = [];
+      if (additions > 0) parts.push(`${additions} addition${additions > 1 ? "s" : ""}`);
+      if (deletions > 0) parts.push(`${deletions} deletion${deletions > 1 ? "s" : ""}`);
+      summary = parts.join(", ");
+    }
+    return {
+      componentName,
+      diffs,
+      summary,
+      hasChanges
+    };
+  }
+  /**
+   * Format diffs for AI prompt consumption
+   */
+  static formatForPrompt(diffs) {
+    if (diffs.length === 0) {
+      return "No changes detected.";
+    }
+    const lines = [];
+    for (const diff of diffs) {
+      const linePrefix = diff.lineNumber ? `Line ${diff.lineNumber}: ` : "";
+      if (diff.type === "addition") {
+        lines.push(`${linePrefix}+ ${diff.modified}`);
+      } else if (diff.type === "deletion") {
+        lines.push(`${linePrefix}- ${diff.original}`);
+      } else if (diff.type === "change") {
+        lines.push(`${linePrefix}"${diff.original}" \u2192 "${diff.modified}"`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Format component diffs for AI prompt
+   */
+  static formatComponentDiffsForPrompt(componentDiffs) {
+    const sections = [];
+    for (const cd of componentDiffs) {
+      if (!cd.hasChanges) continue;
+      sections.push(`## Changes to ${cd.componentName}:`);
+      sections.push(this.formatForPrompt(cd.diffs));
+      sections.push("");
+    }
+    return sections.join("\n");
+  }
+  /**
+   * Create a unified diff view
+   */
+  static unifiedDiff(original, modified, options) {
+    const filename = options?.filename || "content";
+    const patch = Diff.createPatch(filename, original, modified, "", "", {
+      context: options?.context ?? 3
+    });
+    return patch;
+  }
+  /**
+   * Extract corrections from diffs (specific text replacements)
+   */
+  static extractCorrections(original, modified, sourceFile) {
+    const wordDiffs = Diff.diffWords(original, modified);
+    const corrections = [];
+    let i = 0;
+    while (i < wordDiffs.length) {
+      const current = wordDiffs[i];
+      if (current.removed && i + 1 < wordDiffs.length && wordDiffs[i + 1].added) {
+        const removed = current.value.trim();
+        const added = wordDiffs[i + 1].value.trim();
+        if (removed && added && removed !== added) {
+          corrections.push({
+            original: removed,
+            corrected: added,
+            sourceFile
+          });
+        }
+        i += 2;
+      } else {
+        i++;
+      }
+    }
+    return corrections;
+  }
+  /**
+   * Check if two strings are meaningfully different
+   * (ignoring whitespace differences)
+   */
+  static hasSignificantChanges(original, modified) {
+    const normalizedOriginal = original.replace(/\s+/g, " ").trim();
+    const normalizedModified = modified.replace(/\s+/g, " ").trim();
+    return normalizedOriginal !== normalizedModified;
+  }
+};
+
+// src/edit/prompts.ts
+var PromptBuilder = class {
+  /**
+   * Build prompt for AI-first mode (user provides instructions)
+   */
+  static buildAIPrompt(userPrompt, component, entityContext, currentContent) {
+    const sections = [];
+    sections.push(`## Instructions for ${component}`);
+    sections.push(userPrompt);
+    sections.push("");
+    sections.push("## Entity Context");
+    sections.push(`- PI: ${entityContext.pi}`);
+    sections.push(`- Current version: ${entityContext.ver}`);
+    if (entityContext.parentPi) {
+      sections.push(`- Parent: ${entityContext.parentPi}`);
+    }
+    if (entityContext.childrenCount > 0) {
+      sections.push(`- Children: ${entityContext.childrenCount}`);
+    }
+    sections.push("");
+    if (currentContent) {
+      sections.push(`## Current ${component} content for reference:`);
+      sections.push("```");
+      sections.push(currentContent.slice(0, 2e3));
+      if (currentContent.length > 2e3) {
+        sections.push("... [truncated]");
+      }
+      sections.push("```");
+    }
+    return sections.join("\n");
+  }
+  /**
+   * Build prompt incorporating manual edits and diffs
+   */
+  static buildEditReviewPrompt(componentDiffs, corrections, component, userInstructions) {
+    const sections = [];
+    sections.push("## Manual Edits Made");
+    sections.push("");
+    sections.push("The following manual edits were made to this entity:");
+    sections.push("");
+    const diffContent = DiffEngine.formatComponentDiffsForPrompt(componentDiffs);
+    if (diffContent) {
+      sections.push(diffContent);
+    }
+    if (corrections.length > 0) {
+      sections.push("## Corrections Identified");
+      sections.push("");
+      for (const correction of corrections) {
+        const source = correction.sourceFile ? ` (in ${correction.sourceFile})` : "";
+        sections.push(`- "${correction.original}" \u2192 "${correction.corrected}"${source}`);
+      }
+      sections.push("");
+    }
+    sections.push("## Instructions");
+    if (userInstructions) {
+      sections.push(userInstructions);
+    } else {
+      sections.push(
+        `Update the ${component} to accurately reflect these changes. Ensure any corrections are incorporated and the content is consistent.`
+      );
+    }
+    sections.push("");
+    sections.push("## Guidance");
+    switch (component) {
+      case "pinax":
+        sections.push(
+          "Update metadata fields to reflect any corrections. Pay special attention to dates, names, and other factual information that may have been corrected."
+        );
+        break;
+      case "description":
+        sections.push(
+          "Regenerate the description incorporating the changes. Maintain the overall tone and structure while ensuring accuracy based on the corrections."
+        );
+        break;
+      case "cheimarros":
+        sections.push(
+          "Update the knowledge graph to reflect any new or corrected entities, relationships, and facts identified in the changes."
+        );
+        break;
+    }
+    return sections.join("\n");
+  }
+  /**
+   * Build cascade-aware prompt additions
+   */
+  static buildCascadePrompt(basePrompt, cascadeContext) {
+    const sections = [basePrompt];
+    sections.push("");
+    sections.push("## Cascade Context");
+    sections.push("");
+    sections.push(
+      "This edit is part of a cascading update. After updating this entity, parent entities will also be updated to reflect these changes."
+    );
+    sections.push("");
+    if (cascadeContext.path.length > 1) {
+      sections.push(`Cascade path: ${cascadeContext.path.join(" \u2192 ")}`);
+      sections.push(`Depth: ${cascadeContext.depth}`);
+    }
+    if (cascadeContext.stopAtPi) {
+      sections.push(`Cascade will stop at: ${cascadeContext.stopAtPi}`);
+    }
+    sections.push("");
+    sections.push(
+      "Ensure the content accurately represents the source material so parent aggregations will be correct."
+    );
+    return sections.join("\n");
+  }
+  /**
+   * Build a general prompt combining multiple instructions
+   */
+  static buildCombinedPrompt(generalPrompt, componentPrompt, component) {
+    const sections = [];
+    if (generalPrompt) {
+      sections.push("## General Instructions");
+      sections.push(generalPrompt);
+      sections.push("");
+    }
+    if (componentPrompt) {
+      sections.push(`## Specific Instructions for ${component}`);
+      sections.push(componentPrompt);
+      sections.push("");
+    }
+    if (sections.length === 0) {
+      return `Regenerate the ${component} based on the current entity content.`;
+    }
+    return sections.join("\n");
+  }
+  /**
+   * Build prompt for correction-based updates
+   */
+  static buildCorrectionPrompt(corrections) {
+    if (corrections.length === 0) {
+      return "";
+    }
+    const sections = [];
+    sections.push("## Corrections Applied");
+    sections.push("");
+    sections.push("The following corrections were made to the source content:");
+    sections.push("");
+    for (const correction of corrections) {
+      const source = correction.sourceFile ? ` in ${correction.sourceFile}` : "";
+      sections.push(`- "${correction.original}" was corrected to "${correction.corrected}"${source}`);
+      if (correction.context) {
+        sections.push(`  Context: ${correction.context}`);
+      }
+    }
+    sections.push("");
+    sections.push(
+      "Update the metadata and description to reflect these corrections. Previous content may have contained errors based on the incorrect text."
+    );
+    return sections.join("\n");
+  }
+  /**
+   * Get component-specific regeneration guidance
+   */
+  static getComponentGuidance(component) {
+    switch (component) {
+      case "pinax":
+        return "Extract and structure metadata including: institution, creator, title, date range, subjects, type, and other relevant fields. Ensure accuracy based on the source content.";
+      case "description":
+        return "Generate a clear, informative description that summarizes the entity content. Focus on what the material contains, its historical significance, and context. Write for a general audience unless otherwise specified.";
+      case "cheimarros":
+        return "Extract entities (people, places, organizations, events) and their relationships. Build a knowledge graph that captures the key facts and connections in the content.";
+      default:
+        return "";
+    }
+  }
+};
+
+// src/edit/session.ts
+var DEFAULT_SCOPE = {
+  components: [],
+  cascade: false
+};
+var DEFAULT_POLL_OPTIONS = {
+  intervalMs: 2e3,
+  timeoutMs: 3e5
+  // 5 minutes
+};
+var EditSession = class {
+  constructor(client, pi, config) {
+    this.entity = null;
+    this.loadedComponents = {};
+    // AI mode state
+    this.prompts = {};
+    // Manual mode state
+    this.editedContent = {};
+    this.corrections = [];
+    // Scope
+    this.scope = { ...DEFAULT_SCOPE };
+    // Execution state
+    this.submitting = false;
+    this.result = null;
+    this.statusUrl = null;
+    this.client = client;
+    this.pi = pi;
+    this.mode = config?.mode ?? "ai-prompt";
+    this.aiReviewEnabled = config?.aiReviewEnabled ?? true;
+  }
+  // ===========================================================================
+  // Loading
+  // ===========================================================================
+  /**
+   * Load the entity and its key components
+   */
+  async load() {
+    this.entity = await this.client.getEntity(this.pi);
+    const priorityComponents = ["description.md", "pinax.json", "cheimarros.json"];
+    await Promise.all(
+      priorityComponents.map(async (name) => {
+        const cid = this.entity.components[name];
+        if (cid) {
+          try {
+            this.loadedComponents[name] = await this.client.getContent(cid);
+          } catch {
+          }
+        }
+      })
+    );
+  }
+  /**
+   * Load a specific component on demand
+   */
+  async loadComponent(name) {
+    if (this.loadedComponents[name]) {
+      return this.loadedComponents[name];
+    }
+    if (!this.entity) {
+      throw new ValidationError2("Session not loaded");
+    }
+    const cid = this.entity.components[name];
+    if (!cid) {
+      return void 0;
+    }
+    const content = await this.client.getContent(cid);
+    this.loadedComponents[name] = content;
+    return content;
+  }
+  /**
+   * Get the loaded entity
+   */
+  getEntity() {
+    if (!this.entity) {
+      throw new ValidationError2("Session not loaded. Call load() first.");
+    }
+    return this.entity;
+  }
+  /**
+   * Get loaded component content
+   */
+  getComponents() {
+    return { ...this.loadedComponents };
+  }
+  // ===========================================================================
+  // AI Prompt Mode
+  // ===========================================================================
+  /**
+   * Set a prompt for AI regeneration
+   */
+  setPrompt(target, prompt) {
+    if (this.mode === "manual-only") {
+      throw new ValidationError2("Cannot set prompts in manual-only mode");
+    }
+    this.prompts[target] = prompt;
+  }
+  /**
+   * Get all prompts
+   */
+  getPrompts() {
+    return { ...this.prompts };
+  }
+  /**
+   * Clear a prompt
+   */
+  clearPrompt(target) {
+    delete this.prompts[target];
+  }
+  // ===========================================================================
+  // Manual Edit Mode
+  // ===========================================================================
+  /**
+   * Set edited content for a component
+   */
+  setContent(componentName, content) {
+    if (this.mode === "ai-prompt") {
+      throw new ValidationError2("Cannot set content in ai-prompt mode");
+    }
+    this.editedContent[componentName] = content;
+  }
+  /**
+   * Get all edited content
+   */
+  getEditedContent() {
+    return { ...this.editedContent };
+  }
+  /**
+   * Clear edited content for a component
+   */
+  clearContent(componentName) {
+    delete this.editedContent[componentName];
+  }
+  /**
+   * Add a correction (for OCR fixes, etc.)
+   */
+  addCorrection(original, corrected, sourceFile) {
+    this.corrections.push({ original, corrected, sourceFile });
+  }
+  /**
+   * Get all corrections
+   */
+  getCorrections() {
+    return [...this.corrections];
+  }
+  /**
+   * Clear corrections
+   */
+  clearCorrections() {
+    this.corrections = [];
+  }
+  // ===========================================================================
+  // Scope Configuration
+  // ===========================================================================
+  /**
+   * Set the edit scope
+   */
+  setScope(scope) {
+    this.scope = { ...this.scope, ...scope };
+  }
+  /**
+   * Get the current scope
+   */
+  getScope() {
+    return { ...this.scope };
+  }
+  // ===========================================================================
+  // Preview & Summary
+  // ===========================================================================
+  /**
+   * Get diffs for manual changes
+   */
+  getDiff() {
+    const diffs = [];
+    for (const [name, edited] of Object.entries(this.editedContent)) {
+      const original = this.loadedComponents[name] || "";
+      if (DiffEngine.hasSignificantChanges(original, edited)) {
+        diffs.push(DiffEngine.createComponentDiff(name, original, edited));
+      }
+    }
+    return diffs;
+  }
+  /**
+   * Preview what prompts will be sent to AI
+   */
+  previewPrompt() {
+    const result = {};
+    if (!this.entity) return result;
+    const entityContext = {
+      pi: this.entity.pi,
+      ver: this.entity.ver,
+      parentPi: this.entity.parent_pi,
+      childrenCount: this.entity.children_pi.length,
+      currentContent: this.loadedComponents
+    };
+    for (const component of this.scope.components) {
+      let prompt;
+      if (this.mode === "ai-prompt") {
+        const componentPrompt = this.prompts[component];
+        const generalPrompt = this.prompts["general"];
+        const combined = PromptBuilder.buildCombinedPrompt(generalPrompt, componentPrompt, component);
+        prompt = PromptBuilder.buildAIPrompt(
+          combined,
+          component,
+          entityContext,
+          this.loadedComponents[`${component}.json`] || this.loadedComponents[`${component}.md`]
+        );
+      } else {
+        const diffs = this.getDiff();
+        const userInstructions = this.prompts["general"] || this.prompts[component];
+        prompt = PromptBuilder.buildEditReviewPrompt(diffs, this.corrections, component, userInstructions);
+      }
+      if (this.scope.cascade) {
+        prompt = PromptBuilder.buildCascadePrompt(prompt, {
+          path: [this.entity.pi, this.entity.parent_pi || "root"].filter(Boolean),
+          depth: 0,
+          stopAtPi: this.scope.stopAtPi
+        });
+      }
+      result[component] = prompt;
+    }
+    return result;
+  }
+  /**
+   * Get a summary of pending changes
+   */
+  getChangeSummary() {
+    const diffs = this.getDiff();
+    const hasManualEdits = diffs.some((d) => d.hasChanges);
+    return {
+      mode: this.mode,
+      hasManualEdits,
+      editedComponents: Object.keys(this.editedContent),
+      corrections: [...this.corrections],
+      prompts: { ...this.prompts },
+      scope: { ...this.scope },
+      willRegenerate: [...this.scope.components],
+      willCascade: this.scope.cascade,
+      willSave: hasManualEdits,
+      willReprocess: this.scope.components.length > 0
+    };
+  }
+  // ===========================================================================
+  // Execution
+  // ===========================================================================
+  /**
+   * Submit changes (saves first if manual edits, then reprocesses)
+   */
+  async submit(note) {
+    if (this.submitting) {
+      throw new ValidationError2("Submit already in progress");
+    }
+    if (!this.entity) {
+      throw new ValidationError2("Session not loaded. Call load() first.");
+    }
+    this.submitting = true;
+    this.result = {};
+    try {
+      const diffs = this.getDiff();
+      const hasManualEdits = diffs.some((d) => d.hasChanges);
+      if (hasManualEdits) {
+        const componentUpdates = {};
+        for (const [name, content] of Object.entries(this.editedContent)) {
+          const original = this.loadedComponents[name] || "";
+          if (DiffEngine.hasSignificantChanges(original, content)) {
+            const cid = await this.client.uploadContent(content, name);
+            componentUpdates[name] = cid;
+          }
+        }
+        const version = await this.client.updateEntity(this.pi, {
+          expect_tip: this.entity.manifest_cid,
+          components: componentUpdates,
+          note
+        });
+        this.result.saved = {
+          pi: version.pi,
+          newVersion: version.ver,
+          newTip: version.tip
+        };
+        this.entity.manifest_cid = version.tip;
+        this.entity.ver = version.ver;
+      }
+      if (this.scope.components.length > 0) {
+        const customPrompts = this.buildCustomPrompts();
+        const reprocessResult = await this.client.reprocess({
+          pi: this.pi,
+          phases: this.scope.components,
+          cascade: this.scope.cascade,
+          options: {
+            stop_at_pi: this.scope.stopAtPi,
+            custom_prompts: customPrompts,
+            custom_note: note
+          }
+        });
+        this.result.reprocess = reprocessResult;
+        this.statusUrl = reprocessResult.status_url;
+      }
+      return this.result;
+    } finally {
+      this.submitting = false;
+    }
+  }
+  /**
+   * Wait for reprocessing to complete
+   */
+  async waitForCompletion(options) {
+    const opts = { ...DEFAULT_POLL_OPTIONS, ...options };
+    if (!this.statusUrl) {
+      return {
+        phase: "complete",
+        saveComplete: true
+      };
+    }
+    const startTime = Date.now();
+    let isFirstPoll = true;
+    while (true) {
+      const status = await this.client.getReprocessStatus(this.statusUrl, isFirstPoll);
+      isFirstPoll = false;
+      const editStatus = {
+        phase: status.status === "DONE" ? "complete" : status.status === "ERROR" ? "error" : "reprocessing",
+        saveComplete: true,
+        reprocessStatus: status,
+        error: status.error
+      };
+      if (opts.onProgress) {
+        opts.onProgress(editStatus);
+      }
+      if (status.status === "DONE" || status.status === "ERROR") {
+        return editStatus;
+      }
+      if (Date.now() - startTime > opts.timeoutMs) {
+        return {
+          phase: "error",
+          saveComplete: true,
+          reprocessStatus: status,
+          error: "Timeout waiting for reprocessing to complete"
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, opts.intervalMs));
+    }
+  }
+  /**
+   * Get current status without waiting
+   */
+  async getStatus() {
+    if (!this.statusUrl) {
+      return {
+        phase: this.result?.saved ? "complete" : "idle",
+        saveComplete: !!this.result?.saved
+      };
+    }
+    const status = await this.client.getReprocessStatus(this.statusUrl);
+    return {
+      phase: status.status === "DONE" ? "complete" : status.status === "ERROR" ? "error" : "reprocessing",
+      saveComplete: true,
+      reprocessStatus: status,
+      error: status.error
+    };
+  }
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+  buildCustomPrompts() {
+    const custom = {};
+    if (this.mode === "ai-prompt") {
+      if (this.prompts["general"]) custom.general = this.prompts["general"];
+      if (this.prompts["pinax"]) custom.pinax = this.prompts["pinax"];
+      if (this.prompts["description"]) custom.description = this.prompts["description"];
+      if (this.prompts["cheimarros"]) custom.cheimarros = this.prompts["cheimarros"];
+    } else {
+      const diffs = this.getDiff();
+      const diffContext = DiffEngine.formatComponentDiffsForPrompt(diffs);
+      const correctionContext = PromptBuilder.buildCorrectionPrompt(this.corrections);
+      const basePrompt = [diffContext, correctionContext, this.prompts["general"]].filter(Boolean).join("\n\n");
+      if (basePrompt) {
+        custom.general = basePrompt;
+      }
+      if (this.prompts["pinax"]) custom.pinax = this.prompts["pinax"];
+      if (this.prompts["description"]) custom.description = this.prompts["description"];
+      if (this.prompts["cheimarros"]) custom.cheimarros = this.prompts["cheimarros"];
+    }
+    return custom;
+  }
+};
+
+// src/content/errors.ts
+var ContentError = class extends Error {
+  constructor(message, code2 = "CONTENT_ERROR", details) {
+    super(message);
+    this.code = code2;
+    this.details = details;
+    this.name = "ContentError";
+  }
+};
+var EntityNotFoundError2 = class extends ContentError {
+  constructor(pi) {
+    super(`Entity not found: ${pi}`, "ENTITY_NOT_FOUND", { pi });
+    this.name = "EntityNotFoundError";
+  }
+};
+var ContentNotFoundError = class extends ContentError {
+  constructor(cid) {
+    super(`Content not found: ${cid}`, "CONTENT_NOT_FOUND", { cid });
+    this.name = "ContentNotFoundError";
+  }
+};
+var ComponentNotFoundError = class extends ContentError {
+  constructor(pi, componentName) {
+    super(
+      `Component '${componentName}' not found on entity ${pi}`,
+      "COMPONENT_NOT_FOUND",
+      { pi, componentName }
+    );
+    this.name = "ComponentNotFoundError";
+  }
+};
+var VersionNotFoundError = class extends ContentError {
+  constructor(pi, selector) {
+    super(
+      `Version not found: ${selector} for entity ${pi}`,
+      "VERSION_NOT_FOUND",
+      { pi, selector }
+    );
+    this.name = "VersionNotFoundError";
+  }
+};
+var NetworkError2 = class extends ContentError {
+  constructor(message, statusCode) {
+    super(message, "NETWORK_ERROR", { statusCode });
+    this.statusCode = statusCode;
+    this.name = "NetworkError";
+  }
+};
+
+// src/content/client.ts
+var ContentClient = class {
+  constructor(config) {
+    this.baseUrl = config.gatewayUrl.replace(/\/$/, "");
+    this.fetchImpl = config.fetchImpl ?? fetch;
+  }
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+  buildUrl(path2, query) {
+    const url = new URL(`${this.baseUrl}${path2}`);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+  async request(path2, options = {}) {
+    const url = this.buildUrl(path2, options.query);
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (options.headers) {
+      Object.entries(options.headers).forEach(([k, v]) => {
+        if (v !== void 0) headers.set(k, v);
+      });
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, { ...options, headers });
+    } catch (err) {
+      throw new NetworkError2(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (response.ok) {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      return await response.text();
+    }
+    let body;
+    const text = await response.text();
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+    if (response.status === 404) {
+      const errorCode = body?.error;
+      if (errorCode === "NOT_FOUND" || errorCode === "ENTITY_NOT_FOUND") {
+        throw new ContentError(
+          body?.message || "Not found",
+          "NOT_FOUND",
+          body
+        );
+      }
+    }
+    const message = body?.error && typeof body.error === "string" ? body.error : body?.message && typeof body.message === "string" ? body.message : `Request failed with status ${response.status}`;
+    throw new ContentError(message, "HTTP_ERROR", {
+      status: response.status,
+      body
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Entity Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Get an entity by its Persistent Identifier (PI).
+   *
+   * @param pi - Persistent Identifier (ULID or test PI with II prefix)
+   * @returns Full entity manifest
+   * @throws EntityNotFoundError if the entity doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * console.log('Version:', entity.ver);
+   * console.log('Components:', Object.keys(entity.components));
+   * ```
+   */
+  async get(pi) {
+    try {
+      return await this.request(`/api/entities/${encodeURIComponent(pi)}`);
+    } catch (err) {
+      if (err instanceof ContentError && err.code === "NOT_FOUND") {
+        throw new EntityNotFoundError2(pi);
+      }
+      throw err;
+    }
+  }
+  /**
+   * List entities with pagination.
+   *
+   * @param options - Pagination and metadata options
+   * @returns Paginated list of entity summaries
+   *
+   * @example
+   * ```typescript
+   * // Get first page
+   * const page1 = await content.list({ limit: 20, include_metadata: true });
+   *
+   * // Get next page
+   * if (page1.next_cursor) {
+   *   const page2 = await content.list({ cursor: page1.next_cursor });
+   * }
+   * ```
+   */
+  async list(options = {}) {
+    return this.request("/api/entities", {
+      query: {
+        limit: options.limit,
+        cursor: options.cursor,
+        include_metadata: options.include_metadata
+      }
+    });
+  }
+  /**
+   * Get version history for an entity.
+   *
+   * @param pi - Persistent Identifier
+   * @param options - Pagination options
+   * @returns Version history (newest first)
+   *
+   * @example
+   * ```typescript
+   * const history = await content.versions('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * console.log('Total versions:', history.items.length);
+   * history.items.forEach(v => {
+   *   console.log(`v${v.ver}: ${v.ts} - ${v.note || 'no note'}`);
+   * });
+   * ```
+   */
+  async versions(pi, options = {}) {
+    try {
+      return await this.request(
+        `/api/entities/${encodeURIComponent(pi)}/versions`,
+        {
+          query: {
+            limit: options.limit,
+            cursor: options.cursor
+          }
+        }
+      );
+    } catch (err) {
+      if (err instanceof ContentError && err.code === "NOT_FOUND") {
+        throw new EntityNotFoundError2(pi);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Get a specific version of an entity.
+   *
+   * @param pi - Persistent Identifier
+   * @param selector - Version selector: 'ver:N' for version number or 'cid:...' for CID
+   * @returns Entity manifest for the specified version
+   *
+   * @example
+   * ```typescript
+   * // Get version 2
+   * const v2 = await content.getVersion('01K75HQQXNTDG7BBP7PS9AWYAN', 'ver:2');
+   *
+   * // Get by CID
+   * const vByCid = await content.getVersion('01K75HQQXNTDG7BBP7PS9AWYAN', 'cid:bafybeih...');
+   * ```
+   */
+  async getVersion(pi, selector) {
+    try {
+      return await this.request(
+        `/api/entities/${encodeURIComponent(pi)}/versions/${encodeURIComponent(selector)}`
+      );
+    } catch (err) {
+      if (err instanceof ContentError && err.code === "NOT_FOUND") {
+        throw new EntityNotFoundError2(pi);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Resolve a PI to its tip CID (fast lookup without fetching manifest).
+   *
+   * @param pi - Persistent Identifier
+   * @returns PI and tip CID
+   *
+   * @example
+   * ```typescript
+   * const { tip } = await content.resolve('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * console.log('Latest manifest CID:', tip);
+   * ```
+   */
+  async resolve(pi) {
+    try {
+      return await this.request(`/api/resolve/${encodeURIComponent(pi)}`);
+    } catch (err) {
+      if (err instanceof ContentError && err.code === "NOT_FOUND") {
+        throw new EntityNotFoundError2(pi);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Get the list of child PIs for an entity (fast, returns only PIs).
+   *
+   * @param pi - Persistent Identifier of parent entity
+   * @returns Array of child PIs
+   *
+   * @example
+   * ```typescript
+   * const childPis = await content.children('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * console.log('Children:', childPis);
+   * ```
+   */
+  async children(pi) {
+    const entity = await this.get(pi);
+    return entity.children_pi || [];
+  }
+  /**
+   * Get all child entities for a parent (fetches full entity for each child).
+   *
+   * @param pi - Persistent Identifier of parent entity
+   * @returns Array of child entities
+   *
+   * @example
+   * ```typescript
+   * const childEntities = await content.childrenEntities('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * childEntities.forEach(child => {
+   *   console.log(`${child.pi}: v${child.ver}`);
+   * });
+   * ```
+   */
+  async childrenEntities(pi) {
+    const childPis = await this.children(pi);
+    if (childPis.length === 0) {
+      return [];
+    }
+    const results = await Promise.allSettled(
+      childPis.map((childPi) => this.get(childPi))
+    );
+    return results.filter((r) => r.status === "fulfilled").map((r) => r.value);
+  }
+  /**
+   * Get the Arke origin block (root of the archive tree).
+   *
+   * @returns Arke origin entity
+   *
+   * @example
+   * ```typescript
+   * const origin = await content.arke();
+   * console.log('Arke origin:', origin.pi);
+   * ```
+   */
+  async arke() {
+    return this.request("/api/arke");
+  }
+  // ---------------------------------------------------------------------------
+  // Content Download
+  // ---------------------------------------------------------------------------
+  /**
+   * Download content by CID.
+   *
+   * Returns Blob in browser environments, Buffer in Node.js.
+   *
+   * @param cid - Content Identifier
+   * @returns Content as Blob (browser) or Buffer (Node)
+   * @throws ContentNotFoundError if the content doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const content = await client.download('bafybeih...');
+   *
+   * // In browser
+   * const url = URL.createObjectURL(content as Blob);
+   *
+   * // In Node.js
+   * fs.writeFileSync('output.bin', content as Buffer);
+   * ```
+   */
+  async download(cid) {
+    const url = this.buildUrl(`/api/cat/${encodeURIComponent(cid)}`);
+    let response;
+    try {
+      response = await this.fetchImpl(url);
+    } catch (err) {
+      throw new NetworkError2(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new ContentNotFoundError(cid);
+      }
+      throw new ContentError(
+        `Failed to download content: ${response.status}`,
+        "DOWNLOAD_ERROR",
+        { status: response.status }
+      );
+    }
+    if (typeof window !== "undefined") {
+      return response.blob();
+    } else {
+      const arrayBuffer = await response.arrayBuffer();
+      return Buffer.from(arrayBuffer);
+    }
+  }
+  /**
+   * Get a direct URL for content by CID.
+   *
+   * This is useful for embedding in img tags or for direct downloads.
+   *
+   * @param cid - Content Identifier
+   * @returns URL string
+   *
+   * @example
+   * ```typescript
+   * const url = content.getUrl('bafybeih...');
+   * // Use in img tag: <img src={url} />
+   * ```
+   */
+  getUrl(cid) {
+    return `${this.baseUrl}/api/cat/${encodeURIComponent(cid)}`;
+  }
+  /**
+   * Stream content by CID.
+   *
+   * @param cid - Content Identifier
+   * @returns ReadableStream of the content
+   * @throws ContentNotFoundError if the content doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const stream = await content.stream('bafybeih...');
+   * const reader = stream.getReader();
+   * while (true) {
+   *   const { done, value } = await reader.read();
+   *   if (done) break;
+   *   // Process chunk
+   * }
+   * ```
+   */
+  async stream(cid) {
+    const url = this.buildUrl(`/api/cat/${encodeURIComponent(cid)}`);
+    let response;
+    try {
+      response = await this.fetchImpl(url);
+    } catch (err) {
+      throw new NetworkError2(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new ContentNotFoundError(cid);
+      }
+      throw new ContentError(
+        `Failed to stream content: ${response.status}`,
+        "STREAM_ERROR",
+        { status: response.status }
+      );
+    }
+    if (!response.body) {
+      throw new ContentError("Response body is not available", "STREAM_ERROR");
+    }
+    return response.body;
+  }
+  // ---------------------------------------------------------------------------
+  // Component Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Download a component from an entity.
+   *
+   * @param entity - Entity containing the component
+   * @param componentName - Name of the component (e.g., 'pinax', 'description', 'source')
+   * @returns Component content as Blob (browser) or Buffer (Node)
+   * @throws ComponentNotFoundError if the component doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * const pinax = await content.getComponent(entity, 'pinax');
+   * ```
+   */
+  async getComponent(entity, componentName) {
+    const cid = entity.components[componentName];
+    if (!cid) {
+      throw new ComponentNotFoundError(entity.pi, componentName);
+    }
+    return this.download(cid);
+  }
+  /**
+   * Get the URL for a component from an entity.
+   *
+   * @param entity - Entity containing the component
+   * @param componentName - Name of the component
+   * @returns URL string
+   * @throws ComponentNotFoundError if the component doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * const imageUrl = content.getComponentUrl(entity, 'source');
+   * // Use in img tag: <img src={imageUrl} />
+   * ```
+   */
+  getComponentUrl(entity, componentName) {
+    const cid = entity.components[componentName];
+    if (!cid) {
+      throw new ComponentNotFoundError(entity.pi, componentName);
+    }
+    return this.getUrl(cid);
+  }
+};
+
+// src/graph/errors.ts
+var GraphError = class extends Error {
+  constructor(message, code2 = "GRAPH_ERROR", details) {
+    super(message);
+    this.code = code2;
+    this.details = details;
+    this.name = "GraphError";
+  }
+};
+var GraphEntityNotFoundError = class extends GraphError {
+  constructor(canonicalId) {
+    super(`Graph entity not found: ${canonicalId}`, "ENTITY_NOT_FOUND", { canonicalId });
+    this.name = "GraphEntityNotFoundError";
+  }
+};
+var NoPathFoundError = class extends GraphError {
+  constructor(sourceIds, targetIds) {
+    super(
+      `No path found between sources and targets`,
+      "NO_PATH_FOUND",
+      { sourceIds, targetIds }
+    );
+    this.name = "NoPathFoundError";
+  }
+};
+var NetworkError3 = class extends GraphError {
+  constructor(message, statusCode) {
+    super(message, "NETWORK_ERROR", { statusCode });
+    this.statusCode = statusCode;
+    this.name = "NetworkError";
+  }
+};
+
+// src/graph/client.ts
+var GraphClient = class {
+  constructor(config) {
+    this.baseUrl = config.gatewayUrl.replace(/\/$/, "");
+    this.fetchImpl = config.fetchImpl ?? fetch;
+  }
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+  buildUrl(path2, query) {
+    const url = new URL(`${this.baseUrl}${path2}`);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+  async request(path2, options = {}) {
+    const url = this.buildUrl(path2, options.query);
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (options.headers) {
+      Object.entries(options.headers).forEach(([k, v]) => {
+        if (v !== void 0) headers.set(k, v);
+      });
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, { ...options, headers });
+    } catch (err) {
+      throw new NetworkError3(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (response.ok) {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      return await response.text();
+    }
+    let body;
+    const text = await response.text();
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+    if (response.status === 404) {
+      throw new GraphError(
+        body?.message || "Not found",
+        "NOT_FOUND",
+        body
+      );
+    }
+    const message = body?.error && typeof body.error === "string" ? body.error : body?.message && typeof body.message === "string" ? body.message : `Request failed with status ${response.status}`;
+    throw new GraphError(message, "HTTP_ERROR", {
+      status: response.status,
+      body
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Entity Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Get an entity by its canonical ID.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns Entity data
+   * @throws GraphEntityNotFoundError if the entity doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await graph.getEntity('uuid-123');
+   * console.log('Entity:', entity.label, entity.type);
+   * ```
+   */
+  async getEntity(canonicalId) {
+    const response = await this.request(
+      `/graphdb/entity/${encodeURIComponent(canonicalId)}`
+    );
+    if (!response.found || !response.entity) {
+      throw new GraphEntityNotFoundError(canonicalId);
+    }
+    return response.entity;
+  }
+  /**
+   * Check if an entity exists by its canonical ID.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns True if entity exists
+   *
+   * @example
+   * ```typescript
+   * if (await graph.entityExists('uuid-123')) {
+   *   console.log('Entity exists');
+   * }
+   * ```
+   */
+  async entityExists(canonicalId) {
+    const response = await this.request(
+      `/graphdb/entity/exists/${encodeURIComponent(canonicalId)}`
+    );
+    return response.exists;
+  }
+  /**
+   * Query entities by code with optional type filter.
+   *
+   * @param code - Entity code to search for
+   * @param type - Optional entity type filter
+   * @returns Matching entities
+   *
+   * @example
+   * ```typescript
+   * // Find by code
+   * const entities = await graph.queryByCode('person_john');
+   *
+   * // With type filter
+   * const people = await graph.queryByCode('john', 'person');
+   * ```
+   */
+  async queryByCode(code2, type) {
+    const response = await this.request(
+      "/graphdb/entity/query",
+      {
+        method: "POST",
+        body: JSON.stringify({ code: code2, type })
+      }
+    );
+    if (!response.found || !response.entity) {
+      return [];
+    }
+    return [response.entity];
+  }
+  /**
+   * Look up entities by code across all PIs.
+   *
+   * @param code - Entity code to search for
+   * @param type - Optional entity type filter
+   * @returns Matching entities
+   *
+   * @example
+   * ```typescript
+   * const entities = await graph.lookupByCode('alice_austen', 'person');
+   * ```
+   */
+  async lookupByCode(code2, type) {
+    const response = await this.request(
+      "/graphdb/entities/lookup-by-code",
+      {
+        method: "POST",
+        body: JSON.stringify({ code: code2, type })
+      }
+    );
+    return response.entities || [];
+  }
+  // ---------------------------------------------------------------------------
+  // PI-based Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * List entities from a specific PI or multiple PIs.
+   *
+   * @param pi - Single PI or array of PIs
+   * @param options - Filter options
+   * @returns Entities from the PI(s)
+   *
+   * @example
+   * ```typescript
+   * // From single PI
+   * const entities = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN');
+   *
+   * // With type filter
+   * const people = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN', { type: 'person' });
+   *
+   * // From multiple PIs
+   * const all = await graph.listEntitiesFromPi(['pi-1', 'pi-2']);
+   * ```
+   */
+  async listEntitiesFromPi(pi, options = {}) {
+    const pis = Array.isArray(pi) ? pi : [pi];
+    const response = await this.request(
+      "/graphdb/entities/list",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          pis,
+          type: options.type
+        })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Get entities with their relationships from a PI.
+   *
+   * This is an optimized query that returns entities along with all their
+   * relationship data in a single request.
+   *
+   * @param pi - Persistent Identifier
+   * @param type - Optional entity type filter
+   * @returns Entities with relationships
+   *
+   * @example
+   * ```typescript
+   * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * entities.forEach(e => {
+   *   console.log(`${e.label} has ${e.relationships.length} relationships`);
+   * });
+   * ```
+   */
+  async getEntitiesWithRelationships(pi, type) {
+    const response = await this.request(
+      "/graphdb/pi/entities-with-relationships",
+      {
+        method: "POST",
+        body: JSON.stringify({ pi, type })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Get the lineage (ancestors and/or descendants) of a PI.
+   *
+   * @param pi - Source PI
+   * @param direction - 'ancestors', 'descendants', or 'both'
+   * @returns Lineage data
+   *
+   * @example
+   * ```typescript
+   * // Get ancestors
+   * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');
+   *
+   * // Get both directions
+   * const full = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'both');
+   * ```
+   */
+  async getLineage(pi, direction = "both", maxHops = 10) {
+    return this.request("/graphdb/pi/lineage", {
+      method: "POST",
+      body: JSON.stringify({ sourcePi: pi, direction, maxHops })
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Relationship Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Get all relationships for an entity.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns Array of relationships
+   *
+   * @example
+   * ```typescript
+   * const relationships = await graph.getRelationships('uuid-123');
+   * relationships.forEach(r => {
+   *   console.log(`${r.direction}: ${r.predicate} -> ${r.target_label}`);
+   * });
+   * ```
+   */
+  async getRelationships(canonicalId) {
+    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(canonicalId)}`);
+    if (!response.found || !response.relationships) {
+      return [];
+    }
+    return response.relationships.map((rel) => ({
+      direction: rel.direction,
+      predicate: rel.predicate,
+      target_id: rel.target_id,
+      target_code: rel.target_code || "",
+      target_label: rel.target_label,
+      target_type: rel.target_type,
+      properties: rel.properties,
+      source_pi: rel.source_pi,
+      created_at: rel.created_at
+    }));
+  }
+  // ---------------------------------------------------------------------------
+  // Path Finding
+  // ---------------------------------------------------------------------------
+  /**
+   * Find shortest paths between sets of entities.
+   *
+   * @param sourceIds - Starting entity IDs
+   * @param targetIds - Target entity IDs
+   * @param options - Path finding options
+   * @returns Found paths
+   *
+   * @example
+   * ```typescript
+   * const paths = await graph.findPaths(
+   *   ['uuid-alice'],
+   *   ['uuid-bob'],
+   *   { max_depth: 4, direction: 'both' }
+   * );
+   *
+   * paths.forEach(path => {
+   *   console.log(`Path of length ${path.length}:`);
+   *   path.edges.forEach(e => {
+   *     console.log(`  ${e.subject_label} -[${e.predicate}]-> ${e.object_label}`);
+   *   });
+   * });
+   * ```
+   */
+  async findPaths(sourceIds, targetIds, options = {}) {
+    const response = await this.request("/graphdb/paths/between", {
+      method: "POST",
+      body: JSON.stringify({
+        source_ids: sourceIds,
+        target_ids: targetIds,
+        max_depth: options.max_depth,
+        direction: options.direction,
+        limit: options.limit
+      })
+    });
+    return response.paths || [];
+  }
+  /**
+   * Find entities of a specific type reachable from starting entities.
+   *
+   * @param startIds - Starting entity IDs
+   * @param targetType - Type of entities to find
+   * @param options - Search options
+   * @returns Reachable entities of the specified type
+   *
+   * @example
+   * ```typescript
+   * // Find all people reachable from an event
+   * const people = await graph.findReachable(
+   *   ['uuid-event'],
+   *   'person',
+   *   { max_depth: 3 }
+   * );
+   * ```
+   */
+  async findReachable(startIds, targetType, options = {}) {
+    const response = await this.request(
+      "/graphdb/paths/reachable",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          start_ids: startIds,
+          target_type: targetType,
+          max_depth: options.max_depth,
+          direction: options.direction,
+          limit: options.limit
+        })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Check the health of the graph service.
+   *
+   * @returns Health status
+   */
+  async health() {
+    return this.request("/graphdb/health", { method: "GET" });
+  }
+};
+export {
+  ArkeUploader,
+  CollectionsClient,
+  CollectionsError,
+  ComponentNotFoundError,
+  ContentClient,
+  ContentError,
+  NetworkError2 as ContentNetworkError,
+  ContentNotFoundError,
+  EditClient,
+  EditError,
+  EditSession,
+  EntityNotFoundError2 as EntityNotFoundError,
+  GraphClient,
+  GraphEntityNotFoundError,
+  GraphError,
+  NetworkError3 as GraphNetworkError,
+  NetworkError,
+  NoPathFoundError,
+  PermissionError,
+  QueryClient,
+  QueryError,
+  ScanError,
+  UploadClient,
+  UploadError,
+  ValidationError,
+  VersionNotFoundError,
+  WorkerAPIError
+};
 //# sourceMappingURL=index.js.map