@arke-institute/sdk 0.1.1 → 0.1.3

package/dist/index.js

@@ -1466,7 +1466,6 @@ var ArkeUploader = class {
 };
 
 // src/upload/client.ts
-init_errors();
 function getUserIdFromToken(token) {
   try {
     const parts = token.split(".");
@@ -1551,22 +1550,12 @@ var UploadClient = class {
    *
    * 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;
-    if (!dryRun) {
-      const permissions = await this.collectionsClient.getPiPermissions(parentPi);
-      if (!permissions.canEdit) {
-        if (!permissions.collection) {
-          throw new ValidationError(
-            `Cannot add files: PI "${parentPi}" is not part of any collection`
-          );
-        }
-        throw new ValidationError(
-          `Cannot add files to collection "${permissions.collection.title}": you need editor or owner role (current role: ${permissions.collection.role || "none"})`
-        );
-      }
-    }
     const uploader = new ArkeUploader({
       gatewayUrl: this.config.gatewayUrl,
       authToken: this.config.authToken,
@@ -1596,15 +1585,2720 @@ var UploadClient = class {
 
 // 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" });
+  }
+  /**
+   * 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.
+   *
+   * 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/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) {
+    super(message);
+    this.code = code2;
+    this.details = details;
+    this.name = "EditError";
+  }
+};
+var EntityNotFoundError = class extends EditError {
+  constructor(id) {
+    super(`Entity not found: ${id}`, "ENTITY_NOT_FOUND", { id });
+    this.name = "EntityNotFoundError";
+  }
+};
+var CASConflictError = class extends EditError {
+  constructor(id, expectedTip, actualTip) {
+    super(
+      `CAS conflict: entity ${id} was modified (expected ${expectedTip}, got ${actualTip})`,
+      "CAS_CONFLICT",
+      { 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 });
+    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, 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 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)
+   */
+  setAuthToken(token) {
+    this.authToken = token;
+  }
+  /**
+   * 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, context) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      try {
+        const response = await fetch(url, options);
+        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);
+          continue;
+        }
+        return response;
+      } catch (error) {
+        lastError = error;
+        if (this.isRetryableError(lastError) && attempt < this.retryConfig.maxRetries) {
+          const delay = this.calculateDelay(attempt);
+          await this.sleep(delay);
+          continue;
+        }
+        throw new NetworkError2(lastError.message);
+      }
+    }
+    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 });
+    }
+  }
+  // ===========================================================================
+  // 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
+    };
+    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 response.json();
+  }
+  // ===========================================================================
+  // Merge Operations
+  // ===========================================================================
+  /**
+   * Merge source entity into target entity
+   */
+  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}`);
+      }
+    }
+    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();
+  }
+  // ===========================================================================
+  // Delete Operations
+  // ===========================================================================
+  /**
+   * Soft delete an entity (creates tombstone, preserves history)
+   */
+  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) {
+      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
+  // ===========================================================================
+  /**
+   * Upload files to IPFS
+   */
+  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) {
+      await this.handleErrorResponse(response, "Upload files");
+    }
+    return response.json();
+  }
+  /**
+   * Upload text content and return CID
+   */
+  async uploadContent(content, filename) {
+    const blob = new Blob([content], { type: "text/plain" });
+    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);
+    }
+    if (!response.ok) {
+      await this.handleErrorResponse(response, `Get content ${cid}`);
+    }
+    return response.text();
+  }
+  /**
+   * Download a DAG node (JSON) by 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) {
+      await this.handleErrorResponse(response, "Init Arke");
+    }
+    return response.json();
+  }
+  // ===========================================================================
+  // Reprocess API Operations (via /reprocess/*)
+  // ===========================================================================
+  /**
+   * Trigger reprocessing for an entity
+   */
+  async reprocess(request) {
+    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(
+        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}`);
+    }
+    return response.json();
+  }
+  /**
+   * Get reprocessing status by batch ID
+   */
+  async getReprocessStatus(statusUrl, isFirstPoll = false) {
+    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() },
+      "Get reprocess status"
+    );
+    if (!response.ok) {
+      throw new EditError(
+        `Failed to fetch reprocess status: ${response.statusText}`,
+        "STATUS_ERROR",
+        { status: response.status }
+      );
+    }
+    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
+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.id,
+      ver: this.entity.ver,
+      parentPi: this.entity.parent_pi,
+      childrenCount: this.entity.children_pi?.length ?? 0,
+      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.id, 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.id,
+          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(id) {
+    super(`Entity not found: ${id}`, "ENTITY_NOT_FOUND", { id });
+    this.name = "EntityNotFoundError";
+  }
+};
+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(id, componentName) {
+    super(
+      `Component '${componentName}' not found on entity ${id}`,
+      "COMPONENT_NOT_FOUND",
+      { id, componentName }
+    );
+    this.name = "ComponentNotFoundError";
+  }
+};
+var VersionNotFoundError = class extends ContentError {
+  constructor(id, selector) {
+    super(
+      `Version not found: ${selector} for entity ${id}`,
+      "VERSION_NOT_FOUND",
+      { id, selector }
+    );
+    this.name = "VersionNotFoundError";
+  }
+};
+var NetworkError3 = 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 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) {
+      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 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 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 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 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;
+  }
+  /**
+   * 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
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.id, 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.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
+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 NetworkError4 = 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 NetworkError4(
+        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
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Code-based Lookups (indexed in GraphDB)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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 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 Extracted 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.
+   *
+   * 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'
+   * @param maxHops - Maximum depth to traverse (default: 10)
+   * @returns Lineage data with PIs at each hop level
+   *
+   * @example
+   * ```typescript
+   * // Get ancestors (parent chain)
+   * 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 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)
+   *
+   * 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
+   * // 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(id, direction = "both") {
+    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(id)}`);
+    if (!response.found || !response.relationships) {
+      return [];
+    }
+    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,
+      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(
+   *   ['entity-alice'],
+   *   ['entity-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(
+   *   ['event-id'],
+   *   '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,
+  NetworkError3 as ContentNetworkError,
+  ContentNotFoundError2 as ContentNotFoundError,
+  EditClient,
+  EditError,
+  EditSession,
+  EntityNotFoundError2 as EntityNotFoundError,
+  GraphClient,
+  GraphEntityNotFoundError,
+  GraphError,
+  NetworkError4 as GraphNetworkError,
   NetworkError,
+  NoPathFoundError,
+  PermissionError,
+  QueryClient,
+  QueryError,
   ScanError,
   UploadClient,
   UploadError,
   ValidationError,
+  VersionNotFoundError,
   WorkerAPIError
 };
 //# sourceMappingURL=index.js.map