@arke-institute/sdk 0.1.2 → 0.1.3

package/dist/index.js

@@ -1809,6 +1809,73 @@ var QueryClient = class {
   async health() {
     return this.request("/query/health", { method: "GET" });
   }
+  /**
+   * Direct semantic search against the vector index.
+   *
+   * This bypasses the path query syntax and directly queries Pinecone for
+   * semantically similar entities. Useful for:
+   * - Simple semantic searches without graph traversal
+   * - Scoped searches filtered by source_pi (collection scope)
+   * - Type-filtered semantic searches
+   *
+   * For graph traversal and path-based queries, use `path()` instead.
+   *
+   * @param text - Search query text
+   * @param options - Search options (namespace, filters, top_k)
+   * @returns Matching entities with similarity scores
+   *
+   * @example
+   * ```typescript
+   * // Simple semantic search
+   * const results = await query.semanticSearch('photographers from New York');
+   *
+   * // Scoped to a specific PI (collection)
+   * const scoped = await query.semanticSearch('portraits', {
+   *   filter: { source_pi: '01K75HQQXNTDG7BBP7PS9AWYAN' },
+   *   top_k: 20,
+   * });
+   *
+   * // Filter by type
+   * const people = await query.semanticSearch('artists', {
+   *   filter: { type: 'person' },
+   * });
+   *
+   * // Search across merged entities from multiple source PIs
+   * const merged = await query.semanticSearch('historical documents', {
+   *   filter: { merged_entities_source_pis: ['pi-1', 'pi-2'] },
+   * });
+   * ```
+   */
+  async semanticSearch(text, options = {}) {
+    let pineconeFilter;
+    if (options.filter) {
+      pineconeFilter = {};
+      if (options.filter.type) {
+        const types = Array.isArray(options.filter.type) ? options.filter.type : [options.filter.type];
+        pineconeFilter.type = types.length === 1 ? { $eq: types[0] } : { $in: types };
+      }
+      if (options.filter.source_pi) {
+        const pis = Array.isArray(options.filter.source_pi) ? options.filter.source_pi : [options.filter.source_pi];
+        pineconeFilter.source_pi = pis.length === 1 ? { $eq: pis[0] } : { $in: pis };
+      }
+      if (options.filter.merged_entities_source_pis) {
+        const pis = Array.isArray(options.filter.merged_entities_source_pis) ? options.filter.merged_entities_source_pis : [options.filter.merged_entities_source_pis];
+        pineconeFilter.merged_entities_source_pis = { $in: pis };
+      }
+      if (Object.keys(pineconeFilter).length === 0) {
+        pineconeFilter = void 0;
+      }
+    }
+    return this.request("/query/search/semantic", {
+      method: "POST",
+      body: JSON.stringify({
+        text,
+        namespace: options.namespace,
+        filter: pineconeFilter,
+        top_k: options.top_k
+      })
+    });
+  }
   /**
    * Search for collections by semantic similarity.
    *
@@ -1843,6 +1910,14 @@ var QueryClient = class {
   }
 };
 
+// src/edit/types.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 10,
+  baseDelay: 100,
+  maxDelay: 5e3,
+  jitterFactor: 0.3
+};
+
 // src/edit/errors.ts
 var EditError = class extends Error {
   constructor(message, code2 = "UNKNOWN_ERROR", details) {
@@ -1853,21 +1928,51 @@ var EditError = class extends Error {
   }
 };
 var EntityNotFoundError = class extends EditError {
-  constructor(pi) {
-    super(`Entity not found: ${pi}`, "ENTITY_NOT_FOUND", { pi });
+  constructor(id) {
+    super(`Entity not found: ${id}`, "ENTITY_NOT_FOUND", { id });
     this.name = "EntityNotFoundError";
   }
 };
 var CASConflictError = class extends EditError {
-  constructor(pi, expectedTip, actualTip) {
+  constructor(id, expectedTip, actualTip) {
     super(
-      `CAS conflict: entity ${pi} was modified (expected ${expectedTip}, got ${actualTip})`,
+      `CAS conflict: entity ${id} was modified (expected ${expectedTip}, got ${actualTip})`,
       "CAS_CONFLICT",
-      { pi, expectedTip, actualTip }
+      { id, expectedTip, actualTip }
     );
     this.name = "CASConflictError";
   }
 };
+var EntityExistsError = class extends EditError {
+  constructor(id) {
+    super(`Entity already exists: ${id}`, "ENTITY_EXISTS", { id });
+    this.name = "EntityExistsError";
+  }
+};
+var MergeError = class extends EditError {
+  constructor(message, sourceId, targetId) {
+    super(message, "MERGE_ERROR", { sourceId, targetId });
+    this.name = "MergeError";
+  }
+};
+var UnmergeError = class extends EditError {
+  constructor(message, sourceId, targetId) {
+    super(message, "UNMERGE_ERROR", { sourceId, targetId });
+    this.name = "UnmergeError";
+  }
+};
+var DeleteError = class extends EditError {
+  constructor(message, id) {
+    super(message, "DELETE_ERROR", { id });
+    this.name = "DeleteError";
+  }
+};
+var UndeleteError = class extends EditError {
+  constructor(message, id) {
+    super(message, "UNDELETE_ERROR", { id });
+    this.name = "UndeleteError";
+  }
+};
 var ReprocessError = class extends EditError {
   constructor(message, batchId) {
     super(message, "REPROCESS_ERROR", { batchId });
@@ -1881,28 +1986,52 @@ var ValidationError2 = class extends EditError {
   }
 };
 var PermissionError = class extends EditError {
-  constructor(message, pi) {
-    super(message, "PERMISSION_DENIED", { pi });
+  constructor(message, id) {
+    super(message, "PERMISSION_DENIED", { id });
     this.name = "PermissionError";
   }
 };
+var NetworkError2 = class extends EditError {
+  constructor(message, statusCode) {
+    super(message, "NETWORK_ERROR", { statusCode });
+    this.name = "NetworkError";
+  }
+};
+var ContentNotFoundError = class extends EditError {
+  constructor(cid) {
+    super(`Content not found: ${cid}`, "CONTENT_NOT_FOUND", { cid });
+    this.name = "ContentNotFoundError";
+  }
+};
+var IPFSError = class extends EditError {
+  constructor(message) {
+    super(message, "IPFS_ERROR");
+    this.name = "IPFSError";
+  }
+};
+var BackendError = class extends EditError {
+  constructor(message) {
+    super(message, "BACKEND_ERROR");
+    this.name = "BackendError";
+  }
+};
 
 // 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 RETRYABLE_STATUS_CODES = [409, 503];
+var RETRYABLE_ERRORS = ["ECONNRESET", "ETIMEDOUT", "fetch failed"];
 var EditClient = class {
   constructor(config) {
     this.gatewayUrl = config.gatewayUrl.replace(/\/$/, "");
     this.authToken = config.authToken;
+    this.network = config.network || "main";
+    this.userId = config.userId;
+    this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retryConfig };
     this.statusUrlTransform = config.statusUrlTransform;
+    this.apiPrefix = config.apiPrefix ?? "/api";
   }
+  // ===========================================================================
+  // Configuration Methods
+  // ===========================================================================
   /**
    * Update the auth token (useful for token refresh)
    */
@@ -1910,135 +2039,505 @@ var EditClient = class {
     this.authToken = token;
   }
   /**
-   * Sleep for a given number of milliseconds
+   * Set the network (main or test)
+   */
+  setNetwork(network) {
+    this.network = network;
+  }
+  /**
+   * Set the user ID for permission checks
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  // ===========================================================================
+  // Internal Helpers
+  // ===========================================================================
+  /**
+   * Build URL with API prefix
    */
+  buildUrl(path2) {
+    return `${this.gatewayUrl}${this.apiPrefix}${path2}`;
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  getHeaders(contentType = "application/json") {
+    const headers = {};
+    if (contentType) {
+      headers["Content-Type"] = contentType;
+    }
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    headers["X-Arke-Network"] = this.network;
+    if (this.userId) {
+      headers["X-User-Id"] = this.userId;
+    }
+    return headers;
+  }
+  calculateDelay(attempt) {
+    const { baseDelay, maxDelay, jitterFactor } = this.retryConfig;
+    const exponentialDelay = baseDelay * Math.pow(2, attempt);
+    const cappedDelay = Math.min(exponentialDelay, maxDelay);
+    const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+    return Math.max(0, cappedDelay + jitter);
+  }
+  isRetryableStatus(status) {
+    return RETRYABLE_STATUS_CODES.includes(status);
+  }
+  isRetryableError(error) {
+    const message = error.message.toLowerCase();
+    return RETRYABLE_ERRORS.some((e) => message.includes(e.toLowerCase()));
+  }
   /**
    * Execute a fetch with exponential backoff retry on transient errors
    */
-  async fetchWithRetry(url, options, retryOptions = DEFAULT_RETRY_OPTIONS) {
+  async fetchWithRetry(url, options, context) {
     let lastError = null;
-    let delay = retryOptions.initialDelayMs;
-    for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= this.retryConfig.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}`);
+        if (this.isRetryableStatus(response.status) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
+          lastError = new Error(`${context}: ${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) {
+        if (this.isRetryableError(lastError) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
           await this.sleep(delay);
-          delay = Math.min(delay * retryOptions.backoffMultiplier, retryOptions.maxDelayMs);
+          continue;
         }
+        throw new NetworkError2(lastError.message);
       }
     }
-    throw lastError || new Error("Request failed after retries");
+    throw lastError || new NetworkError2("Request failed after retries");
+  }
+  /**
+   * Handle common error responses and throw appropriate error types
+   */
+  async handleErrorResponse(response, context) {
+    let errorData = {};
+    try {
+      errorData = await response.json();
+    } catch {
+    }
+    const message = errorData.message || `${context}: ${response.statusText}`;
+    const errorCode = errorData.error || "";
+    switch (response.status) {
+      case 400:
+        throw new ValidationError2(message);
+      case 403:
+        throw new PermissionError(message);
+      case 404:
+        throw new EntityNotFoundError(message);
+      case 409:
+        if (errorCode === "CAS_FAILURE") {
+          const details = errorData.details;
+          throw new CASConflictError(
+            context,
+            details?.expect || "unknown",
+            details?.actual || "unknown"
+          );
+        }
+        if (errorCode === "CONFLICT") {
+          throw new EntityExistsError(message);
+        }
+        throw new EditError(message, errorCode, errorData.details);
+      case 503:
+        if (errorCode === "IPFS_ERROR") {
+          throw new IPFSError(message);
+        }
+        if (errorCode === "BACKEND_ERROR") {
+          throw new BackendError(message);
+        }
+        throw new NetworkError2(message, response.status);
+      default:
+        throw new EditError(message, errorCode || "API_ERROR", { status: response.status });
+    }
   }
-  getHeaders() {
-    const headers = {
-      "Content-Type": "application/json"
+  // ===========================================================================
+  // Entity CRUD Operations
+  // ===========================================================================
+  /**
+   * Create a new entity
+   */
+  async createEntity(request) {
+    const url = this.buildUrl("/entities");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      "Create entity"
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "Create entity");
+    }
+    return response.json();
+  }
+  /**
+   * Get an entity by ID
+   */
+  async getEntity(id) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get entity ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get entity ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * List entities with pagination
+   */
+  async listEntities(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", options.limit.toString());
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.include_metadata) params.set("include_metadata", "true");
+    const queryString = params.toString();
+    const url = this.buildUrl(`/entities${queryString ? `?${queryString}` : ""}`);
+    const response = await this.fetchWithRetry(url, { headers: this.getHeaders() }, "List entities");
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "List entities");
+    }
+    return response.json();
+  }
+  /**
+   * Update an entity (append new version)
+   */
+  async updateEntity(id, update) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(update)
+      },
+      `Update entity ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Update entity ${id}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Version Operations
+  // ===========================================================================
+  /**
+   * List version history for an entity
+   */
+  async listVersions(id, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit) params.set("limit", options.limit.toString());
+    if (options.cursor) params.set("cursor", options.cursor);
+    const queryString = params.toString();
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions${queryString ? `?${queryString}` : ""}`);
+    const response = await this.fetchWithRetry(url, { headers: this.getHeaders() }, `List versions for ${id}`);
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `List versions for ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * Get a specific version of an entity
+   */
+  async getVersion(id, selector) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/versions/${encodeURIComponent(selector)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get version ${selector} for ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get version ${selector} for ${id}`);
+    }
+    return response.json();
+  }
+  /**
+   * Resolve an entity ID to its current tip CID (fast lookup)
+   */
+  async resolve(id) {
+    const url = this.buildUrl(`/resolve/${encodeURIComponent(id)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Resolve ${id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Resolve ${id}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Hierarchy Operations
+  // ===========================================================================
+  /**
+   * Update parent-child hierarchy relationships
+   */
+  async updateHierarchy(request) {
+    const apiRequest = {
+      parent_pi: request.parent_id,
+      expect_tip: request.expect_tip,
+      add_children: request.add_children,
+      remove_children: request.remove_children,
+      note: request.note
     };
-    if (this.authToken) {
-      headers["Authorization"] = `Bearer ${this.authToken}`;
+    const url = this.buildUrl("/hierarchy");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(apiRequest)
+      },
+      `Update hierarchy for ${request.parent_id}`
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Update hierarchy for ${request.parent_id}`);
     }
-    return headers;
+    return response.json();
   }
+  // ===========================================================================
+  // Merge Operations
+  // ===========================================================================
   /**
-   * Handle common error responses
+   * Merge source entity into target entity
    */
-  handleErrorResponse(response, context) {
-    if (response.status === 403) {
-      throw new PermissionError(`Permission denied: ${context}`);
+  async mergeEntity(sourceId, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(sourceId)}/merge`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Merge ${sourceId} into ${request.target_id}`
+    );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new MergeError(
+          error.message || `Merge failed: ${response.statusText}`,
+          sourceId,
+          request.target_id
+        );
+      } catch (e) {
+        if (e instanceof MergeError) throw e;
+        await this.handleErrorResponse(response, `Merge ${sourceId}`);
+      }
     }
-    throw new EditError(
-      `${context}: ${response.statusText}`,
-      "API_ERROR",
-      { status: response.status }
+    return response.json();
+  }
+  /**
+   * Unmerge (restore) a previously merged entity
+   */
+  async unmergeEntity(sourceId, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(sourceId)}/unmerge`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Unmerge ${sourceId}`
     );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new UnmergeError(
+          error.message || `Unmerge failed: ${response.statusText}`,
+          sourceId,
+          request.target_id
+        );
+      } catch (e) {
+        if (e instanceof UnmergeError) throw e;
+        await this.handleErrorResponse(response, `Unmerge ${sourceId}`);
+      }
+    }
+    return response.json();
   }
   // ===========================================================================
-  // IPFS Wrapper Operations (via /api/*)
+  // Delete Operations
   // ===========================================================================
   /**
-   * Fetch an entity by PI
+   * Soft delete an entity (creates tombstone, preserves history)
    */
-  async getEntity(pi) {
-    const response = await fetch(`${this.gatewayUrl}/api/entities/${pi}`, {
-      headers: this.getHeaders()
-    });
-    if (response.status === 404) {
-      throw new EntityNotFoundError(pi);
+  async deleteEntity(id, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/delete`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Delete ${id}`
+    );
+    if (!response.ok) {
+      try {
+        const error = await response.json();
+        throw new DeleteError(error.message || `Delete failed: ${response.statusText}`, id);
+      } catch (e) {
+        if (e instanceof DeleteError) throw e;
+        await this.handleErrorResponse(response, `Delete ${id}`);
+      }
     }
+    return response.json();
+  }
+  /**
+   * Restore a deleted entity
+   */
+  async undeleteEntity(id, request) {
+    const url = this.buildUrl(`/entities/${encodeURIComponent(id)}/undelete`);
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify(request)
+      },
+      `Undelete ${id}`
+    );
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to fetch entity ${pi}`);
+      try {
+        const error = await response.json();
+        throw new UndeleteError(error.message || `Undelete failed: ${response.statusText}`, id);
+      } catch (e) {
+        if (e instanceof UndeleteError) throw e;
+        await this.handleErrorResponse(response, `Undelete ${id}`);
+      }
     }
     return response.json();
   }
+  // ===========================================================================
+  // Content Operations
+  // ===========================================================================
   /**
-   * Fetch content by CID
+   * Upload files to IPFS
    */
-  async getContent(cid) {
-    const response = await fetch(`${this.gatewayUrl}/api/cat/${cid}`, {
-      headers: this.getHeaders()
-    });
+  async upload(files) {
+    let formData;
+    if (files instanceof FormData) {
+      formData = files;
+    } else {
+      formData = new FormData();
+      const fileArray = Array.isArray(files) ? files : [files];
+      for (const file of fileArray) {
+        if (file instanceof File) {
+          formData.append("file", file, file.name);
+        } else {
+          formData.append("file", file, "file");
+        }
+      }
+    }
+    const url = this.buildUrl("/upload");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders(null),
+        // No Content-Type for multipart
+        body: formData
+      },
+      "Upload files"
+    );
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to fetch content ${cid}`);
+      await this.handleErrorResponse(response, "Upload files");
     }
-    return response.text();
+    return response.json();
   }
   /**
-   * Upload content and get CID
+   * Upload text content and return 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 file = new File([blob], filename, { type: "text/plain" });
+    const [result] = await this.upload(file);
+    return result.cid;
+  }
+  /**
+   * Download file content by CID
+   */
+  async getContent(cid) {
+    const url = this.buildUrl(`/cat/${encodeURIComponent(cid)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get content ${cid}`
+    );
+    if (response.status === 404) {
+      throw new ContentNotFoundError(cid);
     }
-    const response = await fetch(`${this.gatewayUrl}/api/upload`, {
-      method: "POST",
-      headers,
-      body: formData
-    });
     if (!response.ok) {
-      this.handleErrorResponse(response, "Failed to upload content");
+      await this.handleErrorResponse(response, `Get content ${cid}`);
     }
-    const result = await response.json();
-    return result[0].cid;
+    return response.text();
   }
   /**
-   * Update an entity with new components
+   * Download a DAG node (JSON) by CID
    */
-  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
-      );
+  async getDag(cid) {
+    const url = this.buildUrl(`/dag/${encodeURIComponent(cid)}`);
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      `Get DAG ${cid}`
+    );
+    if (response.status === 404) {
+      throw new ContentNotFoundError(cid);
+    }
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get DAG ${cid}`);
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Arke Origin Operations
+  // ===========================================================================
+  /**
+   * Get the Arke origin block (genesis entity)
+   */
+  async getArke() {
+    const url = this.buildUrl("/arke");
+    const response = await this.fetchWithRetry(
+      url,
+      { headers: this.getHeaders() },
+      "Get Arke"
+    );
+    if (!response.ok) {
+      await this.handleErrorResponse(response, "Get Arke");
     }
+    return response.json();
+  }
+  /**
+   * Initialize the Arke origin block (creates if doesn't exist)
+   */
+  async initArke() {
+    const url = this.buildUrl("/arke/init");
+    const response = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.getHeaders()
+      },
+      "Init Arke"
+    );
     if (!response.ok) {
-      this.handleErrorResponse(response, `Failed to update entity ${pi}`);
+      await this.handleErrorResponse(response, "Init Arke");
     }
     return response.json();
   }
@@ -2049,16 +2548,20 @@ var EditClient = class {
    * 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
-      })
-    });
+    const response = await this.fetchWithRetry(
+      `${this.gatewayUrl}/reprocess/reprocess`,
+      {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          pi: request.pi,
+          phases: request.phases,
+          cascade: request.cascade,
+          options: request.options
+        })
+      },
+      `Reprocess ${request.pi}`
+    );
     if (response.status === 403) {
       const error = await response.json().catch(() => ({}));
       throw new PermissionError(
@@ -2068,29 +2571,23 @@ var EditClient = class {
     }
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
-      throw new ReprocessError(
-        error.message || `Reprocess failed: ${response.statusText}`,
-        void 0
-      );
+      throw new ReprocessError(error.message || `Reprocess failed: ${response.statusText}`);
     }
     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 delay = isFirstPoll ? 3e3 : this.retryConfig.baseDelay;
+    if (isFirstPoll) {
+      await this.sleep(delay);
+    }
     const response = await this.fetchWithRetry(
       fetchUrl,
       { headers: this.getHeaders() },
-      retryOptions
+      "Get reprocess status"
     );
     if (!response.ok) {
       throw new EditError(
@@ -2101,6 +2598,30 @@ var EditClient = class {
     }
     return response.json();
   }
+  // ===========================================================================
+  // Utility Methods
+  // ===========================================================================
+  /**
+   * Execute an operation with automatic CAS retry
+   */
+  async withCAS(id, operation, maxRetries = 3) {
+    let lastError = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        const entity = await this.getEntity(id);
+        return await operation(entity);
+      } catch (error) {
+        if (error instanceof CASConflictError && attempt < maxRetries - 1) {
+          lastError = error;
+          const delay = this.calculateDelay(attempt);
+          await this.sleep(delay);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError || new EditError("withCAS failed after retries");
+  }
 };
 
 // src/edit/diff.ts
@@ -2618,10 +3139,10 @@ var EditSession = class {
     const result = {};
     if (!this.entity) return result;
     const entityContext = {
-      pi: this.entity.pi,
+      pi: this.entity.id,
       ver: this.entity.ver,
       parentPi: this.entity.parent_pi,
-      childrenCount: this.entity.children_pi.length,
+      childrenCount: this.entity.children_pi?.length ?? 0,
       currentContent: this.loadedComponents
     };
     for (const component of this.scope.components) {
@@ -2643,7 +3164,7 @@ var EditSession = class {
       }
       if (this.scope.cascade) {
         prompt = PromptBuilder.buildCascadePrompt(prompt, {
-          path: [this.entity.pi, this.entity.parent_pi || "root"].filter(Boolean),
+          path: [this.entity.id, this.entity.parent_pi || "root"].filter(Boolean),
           depth: 0,
           stopAtPi: this.scope.stopAtPi
         });
@@ -2704,7 +3225,7 @@ var EditSession = class {
           note
         });
         this.result.saved = {
-          pi: version.pi,
+          pi: version.id,
           newVersion: version.ver,
           newTip: version.tip
         };
@@ -2824,38 +3345,38 @@ var ContentError = class extends Error {
   }
 };
 var EntityNotFoundError2 = class extends ContentError {
-  constructor(pi) {
-    super(`Entity not found: ${pi}`, "ENTITY_NOT_FOUND", { pi });
+  constructor(id) {
+    super(`Entity not found: ${id}`, "ENTITY_NOT_FOUND", { id });
     this.name = "EntityNotFoundError";
   }
 };
-var ContentNotFoundError = class extends ContentError {
+var ContentNotFoundError2 = 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) {
+  constructor(id, componentName) {
     super(
-      `Component '${componentName}' not found on entity ${pi}`,
+      `Component '${componentName}' not found on entity ${id}`,
       "COMPONENT_NOT_FOUND",
-      { pi, componentName }
+      { id, componentName }
     );
     this.name = "ComponentNotFoundError";
   }
 };
 var VersionNotFoundError = class extends ContentError {
-  constructor(pi, selector) {
+  constructor(id, selector) {
     super(
-      `Version not found: ${selector} for entity ${pi}`,
+      `Version not found: ${selector} for entity ${id}`,
       "VERSION_NOT_FOUND",
-      { pi, selector }
+      { id, selector }
     );
     this.name = "VersionNotFoundError";
   }
 };
-var NetworkError2 = class extends ContentError {
+var NetworkError3 = class extends ContentError {
   constructor(message, statusCode) {
     super(message, "NETWORK_ERROR", { statusCode });
     this.statusCode = statusCode;
@@ -2895,7 +3416,7 @@ var ContentClient = class {
     try {
       response = await this.fetchImpl(url, { ...options, headers });
     } catch (err) {
-      throw new NetworkError2(
+      throw new NetworkError3(
         err instanceof Error ? err.message : "Network request failed"
       );
     }
@@ -3149,13 +3670,13 @@ var ContentClient = class {
     try {
       response = await this.fetchImpl(url);
     } catch (err) {
-      throw new NetworkError2(
+      throw new NetworkError3(
         err instanceof Error ? err.message : "Network request failed"
       );
     }
     if (!response.ok) {
       if (response.status === 404) {
-        throw new ContentNotFoundError(cid);
+        throw new ContentNotFoundError2(cid);
       }
       throw new ContentError(
         `Failed to download content: ${response.status}`,
@@ -3211,13 +3732,13 @@ var ContentClient = class {
     try {
       response = await this.fetchImpl(url);
     } catch (err) {
-      throw new NetworkError2(
+      throw new NetworkError3(
         err instanceof Error ? err.message : "Network request failed"
       );
     }
     if (!response.ok) {
       if (response.status === 404) {
-        throw new ContentNotFoundError(cid);
+        throw new ContentNotFoundError2(cid);
       }
       throw new ContentError(
         `Failed to stream content: ${response.status}`,
@@ -3230,6 +3751,45 @@ var ContentClient = class {
     }
     return response.body;
   }
+  /**
+   * Download a DAG node (JSON) by CID.
+   *
+   * Use this to fetch JSON components like properties and relationships.
+   *
+   * @param cid - Content Identifier of the DAG node
+   * @returns Parsed JSON object
+   * @throws ContentNotFoundError if the content doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const relationships = await content.getDag<RelationshipsComponent>(
+   *   entity.components.relationships
+   * );
+   * console.log('Relationships:', relationships.relationships);
+   * ```
+   */
+  async getDag(cid) {
+    const url = this.buildUrl(`/api/dag/${encodeURIComponent(cid)}`);
+    let response;
+    try {
+      response = await this.fetchImpl(url);
+    } catch (err) {
+      throw new NetworkError3(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new ContentNotFoundError2(cid);
+      }
+      throw new ContentError(
+        `Failed to fetch DAG node: ${response.status}`,
+        "DAG_ERROR",
+        { status: response.status }
+      );
+    }
+    return await response.json();
+  }
   // ---------------------------------------------------------------------------
   // Component Helpers
   // ---------------------------------------------------------------------------
@@ -3250,7 +3810,7 @@ var ContentClient = class {
   async getComponent(entity, componentName) {
     const cid = entity.components[componentName];
     if (!cid) {
-      throw new ComponentNotFoundError(entity.pi, componentName);
+      throw new ComponentNotFoundError(entity.id, componentName);
     }
     return this.download(cid);
   }
@@ -3272,10 +3832,56 @@ var ContentClient = class {
   getComponentUrl(entity, componentName) {
     const cid = entity.components[componentName];
     if (!cid) {
-      throw new ComponentNotFoundError(entity.pi, componentName);
+      throw new ComponentNotFoundError(entity.id, componentName);
     }
     return this.getUrl(cid);
   }
+  /**
+   * Get the properties component for an entity.
+   *
+   * @param entity - Entity containing the properties component
+   * @returns Properties object, or null if no properties component exists
+   *
+   * @example
+   * ```typescript
+   * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * const props = await content.getProperties(entity);
+   * if (props) {
+   *   console.log('Title:', props.title);
+   * }
+   * ```
+   */
+  async getProperties(entity) {
+    const cid = entity.components.properties;
+    if (!cid) {
+      return null;
+    }
+    return this.getDag(cid);
+  }
+  /**
+   * Get the relationships component for an entity.
+   *
+   * @param entity - Entity containing the relationships component
+   * @returns Relationships component, or null if no relationships exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * const rels = await content.getRelationships(entity);
+   * if (rels) {
+   *   rels.relationships.forEach(r => {
+   *     console.log(`${r.predicate} -> ${r.target_label}`);
+   *   });
+   * }
+   * ```
+   */
+  async getRelationships(entity) {
+    const cid = entity.components.relationships;
+    if (!cid) {
+      return null;
+    }
+    return this.getDag(cid);
+  }
 };
 
 // src/graph/errors.ts
@@ -3303,7 +3909,7 @@ var NoPathFoundError = class extends GraphError {
     this.name = "NoPathFoundError";
   }
 };
-var NetworkError3 = class extends GraphError {
+var NetworkError4 = class extends GraphError {
   constructor(message, statusCode) {
     super(message, "NETWORK_ERROR", { statusCode });
     this.statusCode = statusCode;
@@ -3343,7 +3949,7 @@ var GraphClient = class {
     try {
       response = await this.fetchImpl(url, { ...options, headers });
     } catch (err) {
-      throw new NetworkError3(
+      throw new NetworkError4(
         err instanceof Error ? err.message : "Network request failed"
       );
     }
@@ -3375,49 +3981,8 @@ var GraphClient = class {
     });
   }
   // ---------------------------------------------------------------------------
-  // Entity Operations
+  // Code-based Lookups (indexed in GraphDB)
   // ---------------------------------------------------------------------------
-  /**
-   * 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.
    *
@@ -3473,11 +4038,14 @@ var GraphClient = class {
   // PI-based Operations
   // ---------------------------------------------------------------------------
   /**
-   * List entities from a specific PI or multiple PIs.
+   * List entities extracted from a specific PI or multiple PIs.
+   *
+   * This returns knowledge graph entities (persons, places, events, etc.)
+   * that were extracted from the given PI(s), not the PI entity itself.
    *
    * @param pi - Single PI or array of PIs
    * @param options - Filter options
-   * @returns Entities from the PI(s)
+   * @returns Extracted entities from the PI(s)
    *
    * @example
    * ```typescript
@@ -3536,13 +4104,17 @@ var GraphClient = class {
   /**
    * Get the lineage (ancestors and/or descendants) of a PI.
    *
+   * This traverses the PI hierarchy (parent_pi/children_pi relationships)
+   * which is indexed in GraphDB for fast lookups.
+   *
    * @param pi - Source PI
    * @param direction - 'ancestors', 'descendants', or 'both'
-   * @returns Lineage data
+   * @param maxHops - Maximum depth to traverse (default: 10)
+   * @returns Lineage data with PIs at each hop level
    *
    * @example
    * ```typescript
-   * // Get ancestors
+   * // Get ancestors (parent chain)
    * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');
    *
    * // Get both directions
@@ -3559,25 +4131,53 @@ var GraphClient = class {
   // Relationship Operations
   // ---------------------------------------------------------------------------
   /**
-   * Get all relationships for an entity.
+   * Get relationships for an entity from the GraphDB index.
+   *
+   * **Important distinction from ContentClient.getRelationships():**
+   * - **ContentClient.getRelationships()**: Returns OUTBOUND relationships only
+   *   (from the entity's relationships.json in IPFS - source of truth)
+   * - **GraphClient.getRelationships()**: Returns BOTH inbound AND outbound
+   *   relationships (from the indexed GraphDB mirror)
    *
-   * @param canonicalId - Entity UUID
-   * @returns Array of relationships
+   * Use this method when you need to find "what references this entity" (inbound)
+   * or want a complete bidirectional view.
+   *
+   * @param id - Entity identifier (works for both PIs and KG entities)
+   * @param direction - Filter by direction: 'outgoing', 'incoming', or 'both' (default)
+   * @returns Array of relationships with direction indicator
    *
    * @example
    * ```typescript
-   * const relationships = await graph.getRelationships('uuid-123');
-   * relationships.forEach(r => {
-   *   console.log(`${r.direction}: ${r.predicate} -> ${r.target_label}`);
+   * // Get all relationships (both directions)
+   * const all = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
+   *
+   * // Get only inbound relationships ("who references this entity?")
+   * const incoming = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'incoming');
+   *
+   * // Get only outbound relationships (similar to IPFS, but from index)
+   * const outgoing = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'outgoing');
+   *
+   * // Process by direction
+   * const rels = await graph.getRelationships('entity-id');
+   * rels.forEach(r => {
+   *   if (r.direction === 'incoming') {
+   *     console.log(`${r.target_label} references this entity via ${r.predicate}`);
+   *   } else {
+   *     console.log(`This entity ${r.predicate} -> ${r.target_label}`);
+   *   }
    * });
    * ```
    */
-  async getRelationships(canonicalId) {
-    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(canonicalId)}`);
+  async getRelationships(id, direction = "both") {
+    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(id)}`);
     if (!response.found || !response.relationships) {
       return [];
     }
-    return response.relationships.map((rel) => ({
+    let relationships = response.relationships;
+    if (direction !== "both") {
+      relationships = relationships.filter((rel) => rel.direction === direction);
+    }
+    return relationships.map((rel) => ({
       direction: rel.direction,
       predicate: rel.predicate,
       target_id: rel.target_id,
@@ -3603,8 +4203,8 @@ var GraphClient = class {
    * @example
    * ```typescript
    * const paths = await graph.findPaths(
-   *   ['uuid-alice'],
-   *   ['uuid-bob'],
+   *   ['entity-alice'],
+   *   ['entity-bob'],
    *   { max_depth: 4, direction: 'both' }
    * );
    *
@@ -3641,7 +4241,7 @@ var GraphClient = class {
    * ```typescript
    * // Find all people reachable from an event
    * const people = await graph.findReachable(
-   *   ['uuid-event'],
+   *   ['event-id'],
    *   'person',
    *   { max_depth: 3 }
    * );
@@ -3679,8 +4279,8 @@ export {
   ComponentNotFoundError,
   ContentClient,
   ContentError,
-  NetworkError2 as ContentNetworkError,
-  ContentNotFoundError,
+  NetworkError3 as ContentNetworkError,
+  ContentNotFoundError2 as ContentNotFoundError,
   EditClient,
   EditError,
   EditSession,
@@ -3688,7 +4288,7 @@ export {
   GraphClient,
   GraphEntityNotFoundError,
   GraphError,
-  NetworkError3 as GraphNetworkError,
+  NetworkError4 as GraphNetworkError,
   NetworkError,
   NoPathFoundError,
   PermissionError,