@arke-institute/sdk 2.3.10 → 2.3.11

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-13T18:00:18.256Z
+ * Generated: 2026-01-14T01:00:30.186Z
  */
 type paths = {
     "/auth/register": {
@@ -2484,6 +2484,121 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/diff": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get diff between entity versions
+         * @description Computes the difference between two versions of an entity.
+         *
+         *     Query parameters:
+         *     - `from`: CID of the "from" version (defaults to prev of "to" version)
+         *     - `to`: CID of the "to" version (defaults to current tip)
+         *     - `format`: Output format - "semantic" (default) or "patch" (RFC 6902)
+         *
+         *     Modes:
+         *     - No params: Compare current tip with its previous version
+         *     - `to` only: Compare that version with its prev
+         *     - `from` only: Compare from that version to current tip
+         *     - Both: Compare any two versions
+         *
+         *     For version 1 entities (no previous version), "from" is null and all content appears as added.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description CID of the "from" version. Defaults to prev of "to" version. */
+                    from?: string;
+                    /** @description CID of the "to" version. Defaults to current tip. */
+                    to?: string;
+                    /** @description Output format: "semantic" (default) or "patch" (RFC 6902) */
+                    format?: "semantic" | "patch";
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Diff computed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["DiffResponse"];
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Insufficient permissions */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Not Found - Resource does not exist */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Entity not found"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/relationships": {
         parameters: {
             query?: never;
@@ -5838,9 +5953,23 @@ type paths = {
          *     ## Query Syntax
          *
          *     ```
-         *     ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
+         *     [SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
          *     ```
          *
+         *     ## Scope Prefixes
+         *
+         *     Control where semantic search looks for entry points. Default is discovery mode.
+         *
+         *     | Prefix | Description | Example |
+         *     |--------|-------------|---------|
+         *     | (none) | **Discovery mode** (default) - find relevant collections, then search within each | `"medical notes"` |
+         *     | `@:collections` | Search for collections themselves | `@:collections "columbia archives"` |
+         *     | `@:collection(id)` | Search within a specific collection | `@:collection(01JCOLL123) "meeting"` |
+         *     | `@:discover` | Explicit discovery mode | `@:discover "research papers"` |
+         *     | `@:public` | Search public domain only | `@:public "orphaned data"` |
+         *
+         *     **Note:** Graph traversal (hops) is always cross-collection regardless of scope.
+         *
          *     ### Entry Points
          *
          *     | Syntax | Description | Example |
@@ -5862,10 +5991,11 @@ type paths = {
          *     ### Examples
          *
          *     ```
-         *     "george washington"                           # Simple semantic search
-         *     "albert einstein" type:person                 # With type filter
-         *     "medical college" -[*]{,4}-> type:file        # Find files connected to concept
-         *     @01KE4ZY... -[*]{,2}-> type:person            # Find people near entity
+         *     "george washington"                           # Discovery mode (default)
+         *     @:collections "columbia university"           # Find collections
+         *     @:collection(01JCOLL123) "faculty meeting"    # Within specific collection
+         *     @:discover "alice" -[*]{,2}-> type:person     # Discover, then traverse
+         *     @01KE4ZY... -[*]{,2}-> type:person            # From exact entity
          *     ```
          */
         post: {
@@ -7842,6 +7972,139 @@ type components = {
             /** @description Whether results were truncated due to limit */
             truncated: boolean;
         };
+        /** @description Metadata about the "from" version (null for version 1) */
+        VersionMeta: {
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+            /**
+             * @description Entity version number
+             * @example 1
+             */
+            ver: number;
+            /**
+             * Format: date-time
+             * @description ISO 8601 datetime
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            ts: string;
+        } | null;
+        PropertyChange: {
+            /** @description Previous value */
+            from?: unknown;
+            /** @description New value */
+            to?: unknown;
+        };
+        PropertiesChanges: {
+            /**
+             * @description Properties that were added
+             * @example {
+             *       "email": "new@example.com"
+             *     }
+             */
+            added: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that were removed (includes old values)
+             * @example {
+             *       "deprecated_field": "old value"
+             *     }
+             */
+            removed: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that changed
+             * @example {
+             *       "name": {
+             *         "from": "Old Name",
+             *         "to": "New Name"
+             *       }
+             *     }
+             */
+            changed: {
+                [key: string]: components["schemas"]["PropertyChange"];
+            };
+        };
+        RelationshipChange: {
+            predicate: string;
+            peer: string;
+            peer_type?: string;
+            peer_label?: string;
+            properties: components["schemas"]["PropertyChange"];
+        };
+        RelationshipsChanges: {
+            /** @description Relationships that were added */
+            added: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships that were removed */
+            removed: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships with changed properties */
+            changed: components["schemas"]["RelationshipChange"][];
+        };
+        SemanticChanges: {
+            properties: components["schemas"]["PropertiesChanges"];
+            relationships: components["schemas"]["RelationshipsChanges"];
+        };
+        SemanticDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "semantic";
+            changes: components["schemas"]["SemanticChanges"];
+        };
+        PatchOperation: {
+            /** @enum {string} */
+            op: "add";
+            path: string;
+            value?: unknown;
+        } | {
+            /** @enum {string} */
+            op: "remove";
+            path: string;
+        } | {
+            /** @enum {string} */
+            op: "replace";
+            path: string;
+            value?: unknown;
+        };
+        PatchDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "patch";
+            /** @description RFC 6902 JSON Patch operations */
+            patch: components["schemas"]["PatchOperation"][];
+        };
+        DiffResponse: components["schemas"]["SemanticDiffResponse"] | components["schemas"]["PatchDiffResponse"];
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-13T18:00:18.256Z
+ * Generated: 2026-01-14T01:00:30.186Z
  */
 type paths = {
     "/auth/register": {
@@ -2484,6 +2484,121 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/diff": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get diff between entity versions
+         * @description Computes the difference between two versions of an entity.
+         *
+         *     Query parameters:
+         *     - `from`: CID of the "from" version (defaults to prev of "to" version)
+         *     - `to`: CID of the "to" version (defaults to current tip)
+         *     - `format`: Output format - "semantic" (default) or "patch" (RFC 6902)
+         *
+         *     Modes:
+         *     - No params: Compare current tip with its previous version
+         *     - `to` only: Compare that version with its prev
+         *     - `from` only: Compare from that version to current tip
+         *     - Both: Compare any two versions
+         *
+         *     For version 1 entities (no previous version), "from" is null and all content appears as added.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description CID of the "from" version. Defaults to prev of "to" version. */
+                    from?: string;
+                    /** @description CID of the "to" version. Defaults to current tip. */
+                    to?: string;
+                    /** @description Output format: "semantic" (default) or "patch" (RFC 6902) */
+                    format?: "semantic" | "patch";
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Diff computed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["DiffResponse"];
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @description Forbidden - Insufficient permissions */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Not Found - Resource does not exist */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Entity not found"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/relationships": {
         parameters: {
             query?: never;
@@ -5838,9 +5953,23 @@ type paths = {
          *     ## Query Syntax
          *
          *     ```
-         *     ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
+         *     [SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
          *     ```
          *
+         *     ## Scope Prefixes
+         *
+         *     Control where semantic search looks for entry points. Default is discovery mode.
+         *
+         *     | Prefix | Description | Example |
+         *     |--------|-------------|---------|
+         *     | (none) | **Discovery mode** (default) - find relevant collections, then search within each | `"medical notes"` |
+         *     | `@:collections` | Search for collections themselves | `@:collections "columbia archives"` |
+         *     | `@:collection(id)` | Search within a specific collection | `@:collection(01JCOLL123) "meeting"` |
+         *     | `@:discover` | Explicit discovery mode | `@:discover "research papers"` |
+         *     | `@:public` | Search public domain only | `@:public "orphaned data"` |
+         *
+         *     **Note:** Graph traversal (hops) is always cross-collection regardless of scope.
+         *
          *     ### Entry Points
          *
          *     | Syntax | Description | Example |
@@ -5862,10 +5991,11 @@ type paths = {
          *     ### Examples
          *
          *     ```
-         *     "george washington"                           # Simple semantic search
-         *     "albert einstein" type:person                 # With type filter
-         *     "medical college" -[*]{,4}-> type:file        # Find files connected to concept
-         *     @01KE4ZY... -[*]{,2}-> type:person            # Find people near entity
+         *     "george washington"                           # Discovery mode (default)
+         *     @:collections "columbia university"           # Find collections
+         *     @:collection(01JCOLL123) "faculty meeting"    # Within specific collection
+         *     @:discover "alice" -[*]{,2}-> type:person     # Discover, then traverse
+         *     @01KE4ZY... -[*]{,2}-> type:person            # From exact entity
          *     ```
          */
         post: {
@@ -7842,6 +7972,139 @@ type components = {
             /** @description Whether results were truncated due to limit */
             truncated: boolean;
         };
+        /** @description Metadata about the "from" version (null for version 1) */
+        VersionMeta: {
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+            /**
+             * @description Entity version number
+             * @example 1
+             */
+            ver: number;
+            /**
+             * Format: date-time
+             * @description ISO 8601 datetime
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            ts: string;
+        } | null;
+        PropertyChange: {
+            /** @description Previous value */
+            from?: unknown;
+            /** @description New value */
+            to?: unknown;
+        };
+        PropertiesChanges: {
+            /**
+             * @description Properties that were added
+             * @example {
+             *       "email": "new@example.com"
+             *     }
+             */
+            added: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that were removed (includes old values)
+             * @example {
+             *       "deprecated_field": "old value"
+             *     }
+             */
+            removed: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that changed
+             * @example {
+             *       "name": {
+             *         "from": "Old Name",
+             *         "to": "New Name"
+             *       }
+             *     }
+             */
+            changed: {
+                [key: string]: components["schemas"]["PropertyChange"];
+            };
+        };
+        RelationshipChange: {
+            predicate: string;
+            peer: string;
+            peer_type?: string;
+            peer_label?: string;
+            properties: components["schemas"]["PropertyChange"];
+        };
+        RelationshipsChanges: {
+            /** @description Relationships that were added */
+            added: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships that were removed */
+            removed: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships with changed properties */
+            changed: components["schemas"]["RelationshipChange"][];
+        };
+        SemanticChanges: {
+            properties: components["schemas"]["PropertiesChanges"];
+            relationships: components["schemas"]["RelationshipsChanges"];
+        };
+        SemanticDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "semantic";
+            changes: components["schemas"]["SemanticChanges"];
+        };
+        PatchOperation: {
+            /** @enum {string} */
+            op: "add";
+            path: string;
+            value?: unknown;
+        } | {
+            /** @enum {string} */
+            op: "remove";
+            path: string;
+        } | {
+            /** @enum {string} */
+            op: "replace";
+            path: string;
+            value?: unknown;
+        };
+        PatchDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "patch";
+            /** @description RFC 6902 JSON Patch operations */
+            patch: components["schemas"]["PatchOperation"][];
+        };
+        DiffResponse: components["schemas"]["SemanticDiffResponse"] | components["schemas"]["PatchDiffResponse"];
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;

package/openapi/spec.json

@@ -2205,6 +2205,374 @@
           "truncated"
         ]
       },
+      "VersionMeta": {
+        "type": "object",
+        "nullable": true,
+        "properties": {
+          "cid": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Content Identifier (CID) - content-addressed hash",
+            "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+          },
+          "ver": {
+            "type": "integer",
+            "minimum": 0,
+            "exclusiveMinimum": true,
+            "description": "Entity version number",
+            "example": 1
+          },
+          "ts": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 datetime",
+            "example": "2025-12-26T12:00:00.000Z"
+          }
+        },
+        "required": [
+          "cid",
+          "ver",
+          "ts"
+        ],
+        "description": "Metadata about the \"from\" version (null for version 1)"
+      },
+      "PropertyChange": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "nullable": true,
+            "description": "Previous value"
+          },
+          "to": {
+            "nullable": true,
+            "description": "New value"
+          }
+        }
+      },
+      "PropertiesChanges": {
+        "type": "object",
+        "properties": {
+          "added": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "Properties that were added",
+            "example": {
+              "email": "new@example.com"
+            }
+          },
+          "removed": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "Properties that were removed (includes old values)",
+            "example": {
+              "deprecated_field": "old value"
+            }
+          },
+          "changed": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/PropertyChange"
+            },
+            "description": "Properties that changed",
+            "example": {
+              "name": {
+                "from": "Old Name",
+                "to": "New Name"
+              }
+            }
+          }
+        },
+        "required": [
+          "added",
+          "removed",
+          "changed"
+        ]
+      },
+      "RelationshipChange": {
+        "type": "object",
+        "properties": {
+          "predicate": {
+            "type": "string",
+            "minLength": 1
+          },
+          "peer": {
+            "type": "string",
+            "minLength": 1
+          },
+          "peer_type": {
+            "type": "string"
+          },
+          "peer_label": {
+            "type": "string"
+          },
+          "properties": {
+            "$ref": "#/components/schemas/PropertyChange"
+          }
+        },
+        "required": [
+          "predicate",
+          "peer",
+          "properties"
+        ]
+      },
+      "RelationshipsChanges": {
+        "type": "object",
+        "properties": {
+          "added": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "predicate": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "peer": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "peer_type": {
+                  "type": "string"
+                },
+                "peer_label": {
+                  "type": "string"
+                },
+                "properties": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "nullable": true
+                  }
+                }
+              },
+              "required": [
+                "predicate",
+                "peer"
+              ],
+              "description": "Entity relationship",
+              "example": {
+                "predicate": "crew",
+                "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
+                "peer_type": "collection"
+              }
+            },
+            "description": "Relationships that were added"
+          },
+          "removed": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "predicate": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "peer": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "peer_type": {
+                  "type": "string"
+                },
+                "peer_label": {
+                  "type": "string"
+                },
+                "properties": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "nullable": true
+                  }
+                }
+              },
+              "required": [
+                "predicate",
+                "peer"
+              ],
+              "description": "Entity relationship",
+              "example": {
+                "predicate": "crew",
+                "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
+                "peer_type": "collection"
+              }
+            },
+            "description": "Relationships that were removed"
+          },
+          "changed": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RelationshipChange"
+            },
+            "description": "Relationships with changed properties"
+          }
+        },
+        "required": [
+          "added",
+          "removed",
+          "changed"
+        ]
+      },
+      "SemanticChanges": {
+        "type": "object",
+        "properties": {
+          "properties": {
+            "$ref": "#/components/schemas/PropertiesChanges"
+          },
+          "relationships": {
+            "$ref": "#/components/schemas/RelationshipsChanges"
+          }
+        },
+        "required": [
+          "properties",
+          "relationships"
+        ]
+      },
+      "SemanticDiffResponse": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+            "description": "Entity ID (ULID format)",
+            "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          },
+          "from": {
+            "$ref": "#/components/schemas/VersionMeta"
+          },
+          "to": {
+            "$ref": "#/components/schemas/VersionMeta"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "semantic"
+            ]
+          },
+          "changes": {
+            "$ref": "#/components/schemas/SemanticChanges"
+          }
+        },
+        "required": [
+          "entity_id",
+          "from",
+          "to",
+          "format",
+          "changes"
+        ]
+      },
+      "PatchOperation": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "op": {
+                "type": "string",
+                "enum": [
+                  "add"
+                ]
+              },
+              "path": {
+                "type": "string"
+              },
+              "value": {
+                "nullable": true
+              }
+            },
+            "required": [
+              "op",
+              "path"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "op": {
+                "type": "string",
+                "enum": [
+                  "remove"
+                ]
+              },
+              "path": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "op",
+              "path"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "op": {
+                "type": "string",
+                "enum": [
+                  "replace"
+                ]
+              },
+              "path": {
+                "type": "string"
+              },
+              "value": {
+                "nullable": true
+              }
+            },
+            "required": [
+              "op",
+              "path"
+            ]
+          }
+        ]
+      },
+      "PatchDiffResponse": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+            "description": "Entity ID (ULID format)",
+            "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          },
+          "from": {
+            "$ref": "#/components/schemas/VersionMeta"
+          },
+          "to": {
+            "$ref": "#/components/schemas/VersionMeta"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "patch"
+            ]
+          },
+          "patch": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PatchOperation"
+            },
+            "description": "RFC 6902 JSON Patch operations"
+          }
+        },
+        "required": [
+          "entity_id",
+          "from",
+          "to",
+          "format",
+          "patch"
+        ]
+      },
+      "DiffResponse": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/SemanticDiffResponse"
+          },
+          {
+            "$ref": "#/components/schemas/PatchDiffResponse"
+          }
+        ]
+      },
       "AddRelationshipResponse": {
         "type": "object",
         "properties": {
@@ -8322,6 +8690,133 @@
         }
       }
     },
+    "/entities/{id}/diff": {
+      "get": {
+        "tags": [
+          "Entities",
+          "Versions"
+        ],
+        "summary": "Get diff between entity versions",
+        "description": "Computes the difference between two versions of an entity.\n\nQuery parameters:\n- `from`: CID of the \"from\" version (defaults to prev of \"to\" version)\n- `to`: CID of the \"to\" version (defaults to current tip)\n- `format`: Output format - \"semantic\" (default) or \"patch\" (RFC 6902)\n\nModes:\n- No params: Compare current tip with its previous version\n- `to` only: Compare that version with its prev\n- `from` only: Compare from that version to current tip\n- Both: Compare any two versions\n\nFor version 1 entities (no previous version), \"from\" is null and all content appears as added.",
+        "x-arke-action": "entity:view",
+        "x-arke-auth": "optional",
+        "x-arke-tier": "standard",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+              "description": "Entity ID (ULID format)",
+              "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+            },
+            "required": true,
+            "description": "Entity ID (ULID)",
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Content Identifier (CID) - content-addressed hash",
+              "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+            },
+            "required": false,
+            "description": "CID of the \"from\" version. Defaults to prev of \"to\" version.",
+            "name": "from",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Content Identifier (CID) - content-addressed hash",
+              "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+            },
+            "required": false,
+            "description": "CID of the \"to\" version. Defaults to current tip.",
+            "name": "to",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "semantic",
+                "patch"
+              ],
+              "default": "semantic"
+            },
+            "required": false,
+            "description": "Output format: \"semantic\" (default) or \"patch\" (RFC 6902)",
+            "name": "format",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Diff computed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DiffResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - Invalid input",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                },
+                "example": {
+                  "error": "Validation failed",
+                  "details": {
+                    "issues": [
+                      {
+                        "path": [
+                          "properties",
+                          "label"
+                        ],
+                        "message": "Required"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - Insufficient permissions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Forbidden: You do not have permission to perform this action"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found - Resource does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Entity not found"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/relationships": {
       "post": {
         "tags": [
@@ -11535,7 +12030,7 @@
           "Query"
         ],
         "summary": "Execute Argo query",
-        "description": "Execute an Argo DSL query for path-based graph traversal.\n\n## Query Syntax\n\n```\nENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...\n```\n\n### Entry Points\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `\"text\"` | Semantic search | `\"george washington\"` |\n| `@id` | Exact entity ID | `@01KE4ZY69F9R40E88PK9S0TQRQ` |\n| `type:X` | All entities of type | `type:person` |\n| `type:X ~ \"text\"` | Semantic search within type | `type:person ~ \"physician\"` |\n\n### Edges (Hops)\n\n| Syntax | Direction |\n|--------|-----------|\n| `-[*]->` | Outgoing |\n| `<-[*]-` | Incoming |\n| `<-[*]->` | Both |\n| `-[*]{,4}->` | Variable depth (1-4) |\n\n### Examples\n\n```\n\"george washington\"                           # Simple semantic search\n\"albert einstein\" type:person                 # With type filter\n\"medical college\" -[*]{,4}-> type:file        # Find files connected to concept\n@01KE4ZY... -[*]{,2}-> type:person            # Find people near entity\n```\n",
+        "description": "Execute an Argo DSL query for path-based graph traversal.\n\n## Query Syntax\n\n```\n[SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...\n```\n\n## Scope Prefixes\n\nControl where semantic search looks for entry points. Default is discovery mode.\n\n| Prefix | Description | Example |\n|--------|-------------|---------|\n| (none) | **Discovery mode** (default) - find relevant collections, then search within each | `\"medical notes\"` |\n| `@:collections` | Search for collections themselves | `@:collections \"columbia archives\"` |\n| `@:collection(id)` | Search within a specific collection | `@:collection(01JCOLL123) \"meeting\"` |\n| `@:discover` | Explicit discovery mode | `@:discover \"research papers\"` |\n| `@:public` | Search public domain only | `@:public \"orphaned data\"` |\n\n**Note:** Graph traversal (hops) is always cross-collection regardless of scope.\n\n### Entry Points\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `\"text\"` | Semantic search | `\"george washington\"` |\n| `@id` | Exact entity ID | `@01KE4ZY69F9R40E88PK9S0TQRQ` |\n| `type:X` | All entities of type | `type:person` |\n| `type:X ~ \"text\"` | Semantic search within type | `type:person ~ \"physician\"` |\n\n### Edges (Hops)\n\n| Syntax | Direction |\n|--------|-----------|\n| `-[*]->` | Outgoing |\n| `<-[*]-` | Incoming |\n| `<-[*]->` | Both |\n| `-[*]{,4}->` | Variable depth (1-4) |\n\n### Examples\n\n```\n\"george washington\"                           # Discovery mode (default)\n@:collections \"columbia university\"           # Find collections\n@:collection(01JCOLL123) \"faculty meeting\"    # Within specific collection\n@:discover \"alice\" -[*]{,2}-> type:person     # Discover, then traverse\n@01KE4ZY... -[*]{,2}-> type:person            # From exact entity\n```\n",
         "x-arke-action": "query:execute",
         "x-arke-auth": "optional",
         "x-arke-tier": "external",

package/openapi/version.json

@@ -1,7 +1,7 @@
 {
   "specVersion": "1.0.0",
   "apiVersion": "1.0.0",
-  "fetchedAt": "2026-01-13T18:00:17.369Z",
+  "fetchedAt": "2026-01-14T01:00:29.332Z",
   "sourceUrl": "https://arke-v1.arke.institute/openapi.json",
   "openApiVersion": "3.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arke-institute/sdk",
-  "version": "2.3.10",
+  "version": "2.3.11",
   "description": "TypeScript SDK for the Arke API - auto-generated from OpenAPI spec",
   "type": "module",
   "main": "dist/index.cjs",