jsi 0.8.1 → 0.9.0

data/lib/jsi/metaschema_node.rb

@@ -1,117 +1,189 @@
 # frozen_string_literal: true
 
 module JSI
-  # A MetaSchemaNode is a JSI instance representing a node in a document that contains a meta-schema.
-  # The root of the meta-schema is pointed to by metaschema_root_ptr.
-  # the schema describing the root of the document is pointed to by root_schema_ptr.
+  # A MetaSchemaNode is a JSI instance representing a node in a document that contains a meta-schema,
+  # or contains a schema describing a meta-schema (e.g. a meta-schema vocabulary schema).
   #
-  # like JSI::Base's normal subclasses, this class represents an instance of a schema set, an instance
-  # which may itself be a schema. unlike JSI::Base, the document containing the instance and its schemas
-  # is the same, and a schema (the meta-schema) may be an instance of itself.
+  # A meta-schema typically has the unique property that it is an instance of itself.
+  # It may also be an instance of a number of other schemas, each of which
+  # may be an instance of the meta-schema, itself, and/or other schemas.
   #
-  # unlike JSI::Base's normal subclasses, the schemas describing the instance are not part of the class.
-  # Since the meta-schema describes itself, attempting to construct a class from the JSI Schema Module of a
-  # schema which is itself an instance of that class results in a causality loop.
-  # instead, a MetaSchemaNode calculates its {#jsi_schemas} and extends itself with their JSI Schema
-  # modules during initialization.
-  # The MetaSchemaNode of the meta-schema is extended with its own JSI Schema Module.
+  # This is not a configuration of schemas/instances that normal JSI::Base instantiation can accommodate.
+  # MetaSchemaNode instead bootstraps each node on initialization, computing and instantiating
+  # the schemas that describe it (other MetaSchemaNode instances) and their schema modules.
+  # This results in a node that is a meta-schema being an instance of its own schema module
+  # (as well as JSI::Schema and JSI::Schema::MetaSchema), and a node that is a schema being an instance of
+  # the meta-schema's schema module (and thereby JSI::Schema).
   #
-  # if the MetaSchemaNode's schemas include its self, it is extended with {JSI::Schema::MetaSchema}.
-  #
-  # a MetaSchemaNode is extended with JSI::Schema when it represents a schema - this is the case when
-  # the meta-schema is one of its schemas.
+  # The meta-schema may be anywhere in a document, though it is rare to put it anywhere but at the root.
+  # The root of the meta-schema is referenced by the {MetaSchemaNode::Conf configured}
+  # {MetaSchemaNode::Conf#metaschema_root_ref `metaschema_root_ref`}.
+  # The schema describing the root of the document is referenced by the configured
+  # {MetaSchemaNode::Conf#root_schema_ref `root_schema_ref`}.
   class MetaSchemaNode < Base
     autoload :BootstrapSchema, 'jsi/metaschema_node/bootstrap_schema'
 
+    # @private - experimental
+    # `self` is a MetaSchemaNode
+    # @param node [MetaSchemaNode, MetaSchemaNode::BootstrapSchema]
+    # @return [Boolean] is `node` a meta-schema?
+    DEFAULT_IS_METASCHEMA = proc do |node|
+      node.jsi_document.equal?(@bootstrap_metaschema.jsi_document) && node.jsi_ptr == @bootstrap_metaschema.jsi_ptr
+    end
+    private_constant(:DEFAULT_IS_METASCHEMA)
+
     include(Base::Immutable)
 
-    # @param jsi_document the document containing the meta-schema.
-    #   this must be frozen recursively; MetaSchemaNode does support mutation.
-    # @param jsi_ptr [JSI::Ptr] ptr to this MetaSchemaNode in jsi_document
-    # @param schema_implementation_modules [Enumerable<Module>] modules which implement the functionality
-    #   of the schema. These are included on the {Schema#jsi_schema_module} of the meta-schema.
-    #   They extend any schema described by the meta-schema, including those in the document containing
-    #   the meta-schema, and the meta-schema itself.
-    #   see {Schema#describes_schema!} param `schema_implementation_modules`.
-    # @param metaschema_root_ptr [JSI::Ptr] ptr to the root of the meta-schema in the jsi_document
-    # @param root_schema_ptr [JSI::Ptr] ptr to the schema describing the root of the jsi_document
+    conf_attrs = {
+      dialect:             {fingerprint: true },
+      metaschema_root_ref: {fingerprint: true },
+      root_schema_ref:     {fingerprint: true },
+      bootstrap_registry:  {fingerprint: true },
+      is_metaschema:       {fingerprint: true },
+    }.freeze
+    Conf = Base::Conf.subclass(*conf_attrs.keys)
+    class Conf end
+    Conf::ATTRS = Base::Conf::ATTRS.merge(conf_attrs)
+
+    # {Base::Conf} with additional configuration for MetaSchemaNode.
+    #
+    # @!attribute dialect
+    #   @return [Schema::Dialect]
+    # @!attribute metaschema_root_ref
+    #   URI reference to the root of the meta-schema.
+    #
+    #   Default: `"#"` resolves to the root of the `jsi_document`.
+    #   @return [Addressable::URI]
+    # @!attribute root_schema_ref
+    #   URI reference to the schema describing the root of the jsi_document.
+    #   When schemas of the meta-schema are in multiple documents, this describes the roots of all instantiated documents.
+    #
+    #   Default: `metaschema_root_ref` value, i.e. the document root is a schema.
+    #   @return [Addressable::URI]
+    # @!attribute bootstrap_registry
+    #   Default: nil
+    #   @return [Registry, nil]
+    class Conf < Base::Conf
+      def initialize(
+          dialect: ,
+          metaschema_root_ref: '#',
+          root_schema_ref: metaschema_root_ref,
+          registry: nil, # overrides Base::Conf default value JSI.registry
+          is_metaschema: DEFAULT_IS_METASCHEMA,
+          **kw
+      )
+        super(
+          dialect: dialect,
+          metaschema_root_ref: Util.uri(metaschema_root_ref, nnil: true),
+          root_schema_ref: Util.uri(root_schema_ref, nnil: true),
+          registry: registry,
+          is_metaschema: is_metaschema,
+          **kw,
+        )
+      end
+    end
+
+    # See {JSI.new_metaschema_node} to instantiate.
+    #
+    # Note: when instantiating MetaSchemaNode directly, the caller must invoke #jsi_initialize_finish.
+    # @api private
     def initialize(
-        jsi_document,
-        jsi_ptr: Ptr[],
-        schema_implementation_modules: ,
-        metaschema_root_ptr: Ptr[],
-        root_schema_ptr: Ptr[],
-        jsi_schema_base_uri: nil,
-        jsi_schema_registry: nil,
-        jsi_content_to_immutable: DEFAULT_CONTENT_TO_IMMUTABLE,
-        jsi_root_node: nil
+        **kw
     )
-      super(jsi_document,
-        jsi_ptr: jsi_ptr,
+      super(
         jsi_indicated_schemas: SchemaSet[],
-        jsi_schema_base_uri: jsi_schema_base_uri,
-        jsi_schema_registry: jsi_schema_registry,
-        jsi_content_to_immutable: jsi_content_to_immutable,
-        jsi_root_node: jsi_root_node,
+        **kw,
       )
 
-      @schema_implementation_modules = schema_implementation_modules = Util.ensure_module_set(schema_implementation_modules)
-      @metaschema_root_ptr = metaschema_root_ptr
-      @root_schema_ptr = root_schema_ptr
+      @initialize_finish_started = false
+      @initialize_finished = false
+      @to_initialize_finish = []
 
-      if jsi_ptr.root? && jsi_schema_base_uri
-        raise(NotImplementedError, "unsupported jsi_schema_base_uri on meta-schema document root")
+      if jsi_ptr.root? && jsi_base_uri
+        raise(NotImplementedError, "unsupported jsi_base_uri on meta-schema document root")
       end
 
-      #chkbug raise(Bug, 'MetaSchemaNode instance must be frozen') unless jsi_node_content.frozen?
+      #chkbug fail(Bug, 'MetaSchemaNode instance must be frozen') unless jsi_node_content.frozen?
+
+      bootstrap_schema_from_ref = proc do |ref_uri|
+        ref_uri_nofrag = ref_uri.merge(fragment: nil)
+
+        if ref_uri_nofrag.empty?
+          ptr = Ptr.from_fragment(ref_uri.fragment).resolve_against(jsi_document) # anchor not supported
+          if jsi_conf.root_schema_ref == jsi_conf.metaschema_root_ref
+            # root is a schema
+            jsi_conf.dialect.bootstrap_schema(
+              jsi_document: jsi_document,
+              jsi_base_uri: nil, # not supported
+              jsi_registry: jsi_conf.bootstrap_registry,
+            ).resource_root_subschema(ptr)
+          else
+            jsi_conf.dialect.bootstrap_schema(
+              jsi_document: jsi_document,
+              jsi_ptr: ptr,
+              jsi_base_uri: nil, # not supported
+              jsi_registry: jsi_conf.bootstrap_registry,
+            )
+          end
+        else
+          # if not fragment-only, ref must be registered in the bootstrap_registry
+          ref = Schema::Ref.new(ref_uri, registry: jsi_conf.bootstrap_registry)
+          ref.resolve
+        end
+      end
 
-      extends = Set[]
+      @bootstrap_metaschema = bootstrap_schema_from_ref[jsi_conf.metaschema_root_ref]
 
       instance_for_schemas = jsi_document
-      bootstrap_schema_class = JSI::SchemaClasses.bootstrap_schema_class(schema_implementation_modules)
-      root_bootstrap_schema = bootstrap_schema_class.new(
-        jsi_document,
-        jsi_ptr: root_schema_ptr,
-        jsi_schema_base_uri: nil, # supplying jsi_schema_base_uri on root bootstrap schema is not supported
-      )
+      root_bootstrap_schema = bootstrap_schema_from_ref[jsi_conf.root_schema_ref]
       our_bootstrap_indicated_schemas = jsi_ptr.tokens.inject(SchemaSet[root_bootstrap_schema]) do |bootstrap_indicated_schemas, tok|
-        bootstrap_schemas = bootstrap_indicated_schemas.inplace_applicator_schemas(instance_for_schemas)
-        child_indicated_schemas = bootstrap_schemas.child_applicator_schemas(tok, instance_for_schemas)
+        child_indicated_schemas = bootstrap_indicated_schemas.each_yield_set do |is, y|
+          is.each_inplace_child_applicator_schema(tok, instance_for_schemas,
+            collect_evaluated_validate: jsi_conf.application_collect_evaluated_validate,
+            &y
+          )
+        end
         instance_for_schemas = instance_for_schemas[tok]
         child_indicated_schemas
       end
-      @indicated_schemas_map = jsi_memomap { bootstrap_schemas_to_msn(our_bootstrap_indicated_schemas) }
+      @indicated_schemas_map = jsi_memomap do
+        SchemaSet.new(our_bootstrap_indicated_schemas) { |s| bootstrap_schema_to_msn(s) }
+      end
 
-      our_bootstrap_schemas = our_bootstrap_indicated_schemas.inplace_applicator_schemas(instance_for_schemas)
+      @bootstrap_schemas = our_bootstrap_indicated_schemas.each_yield_set do |is, y|
+        is.each_inplace_applicator_schema(instance_for_schemas, &y) # note: instance_for_schemas == jsi_node_content now
+      end
+
+      @jsi_schemas = @bootstrap_schemas
 
-      describes_self = false
-      our_bootstrap_schemas.each do |bootstrap_schema|
-        if bootstrap_schema.jsi_ptr == metaschema_root_ptr
+      @bootstrap_schemas.each do |bootstrap_schema|
+        if instance_exec(bootstrap_schema, &jsi_conf.is_metaschema)
           # this is described by the meta-schema, i.e. this is a schema
-          extend Schema
-          schema_implementation_modules.each do |schema_implementation_module|
-            extend schema_implementation_module
+          define_singleton_method(:dialect) { jsi_conf.dialect }
+          extend(Schema)
+
+          if jsi_registry && jsi_resource_uris.any? { |uri| !jsi_registry.registered?(uri) }
+            jsi_registry.register_immediate(self)
           end
-          extends += schema_implementation_modules
-        end
-        if bootstrap_schema.jsi_ptr == jsi_ptr
-          # this is the meta-schema (it is described by itself)
-          describes_self = true
         end
       end
+    end
+
+    # @api private
+    def jsi_initialize_finish
+      return self if @initialize_finish_started
+      @initialize_finish_started = true
 
-      @jsi_schemas = bootstrap_schemas_to_msn(our_bootstrap_schemas)
+      @jsi_schemas = SchemaSet.new(@bootstrap_schemas) { |s| bootstrap_schema_to_msn(s) }
 
       # note: jsi_schemas must already be set for jsi_schema_module to be used/extended
-      if describes_self
-        describes_schema!(schema_implementation_modules)
+      if instance_exec(self, &jsi_conf.is_metaschema)
+        describes_schema!(jsi_conf.dialect)
       end
 
       extends_for_instance = JSI::SchemaClasses.includes_for(jsi_node_content)
-      extends.merge(extends_for_instance)
-      extends.freeze
 
-      conflicting_modules = Set[self.class] + extends + @jsi_schemas.map(&:jsi_schema_module)
+      conflicting_modules = Set[self.class] + extends_for_instance + @jsi_schemas.map(&:jsi_schema_module)
       reader_modules = @jsi_schemas.map do |schema|
         JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
       end
@@ -128,19 +200,15 @@ module JSI
       @jsi_schemas.each do |schema|
         extend schema.jsi_schema_module
       end
-    end
-
-    # Set of modules to apply to schemas that are instances of (described by) the meta-schema
-    # @return [Set<Module>]
-    attr_reader :schema_implementation_modules
 
-    # ptr to the root of the meta-schema in the jsi_document
-    # @return [JSI::Ptr]
-    attr_reader :metaschema_root_ptr
+      @initialize_finished = true
+      while !@to_initialize_finish.empty?
+        node = @to_initialize_finish.shift
+        node.jsi_initialize_finish
+      end
 
-    # ptr to the schema of the root of the jsi_document
-    # @return [JSI::Ptr]
-    attr_reader :root_schema_ptr
+      jsi_initialized
+    end
 
     # JSI Schemas describing this MetaSchemaNode
     # @return [JSI::SchemaSet]
@@ -152,15 +220,10 @@ module JSI
       @indicated_schemas_map[]
     end
 
-    # see {Base#jsi_child}
-    def jsi_child(token, as_jsi: )
-      child_node = @root_descendent_node_map[ptr: jsi_ptr[token]]
-
-      jsi_child_as_jsi(child_node.jsi_node_content, child_node.jsi_schemas, as_jsi) do
-        child_node
-      end
+    # see {Base#jsi_child_node}
+    def jsi_child_node(token)
+      root_descendent_node(jsi_ptr[token])
     end
-    private :jsi_child
 
     # See {Base#jsi_default_child}
     def jsi_default_child(token, as_jsi: )
@@ -168,42 +231,24 @@ module JSI
     end
     private :jsi_default_child # internals for #[] but idk, could be public
 
-    # instantiates a new MetaSchemaNode whose instance is a modified copy of this MetaSchemaNode's instance
-    # @yield [Object] the node content of the instance. the block should result
-    #   in a (nondestructively) modified copy of this.
-    # @return [MetaSchemaNode] modified copy of self
-    def jsi_modified_copy(&block)
-      if jsi_ptr.root?
-        modified_document = jsi_ptr.modified_document_copy(jsi_document, &block)
-        modified_document = jsi_content_to_immutable.call(modified_document) if jsi_content_to_immutable
-        MetaSchemaNode.new(modified_document, **our_initialize_params)
-      else
-        modified_jsi_root_node = jsi_root_node.jsi_modified_copy do |root|
-          jsi_ptr.modified_document_copy(root, &block)
-        end
-        modified_jsi_root_node.jsi_descendent_node(jsi_ptr)
-      end
+    # @raise [NotImplementedError] not implemented for MetaSchemaNode
+    def jsi_modified_copy(**)
+      # this had an implementation previously (see git history). but for 2020-12, support for multiple
+      # mutually-descriptive schemas as well as dynamic scope makes instantiating a modified copy that
+      # preserves self-descriptive/mutually-descriptive relationships generally infeasible.
+      raise(NotImplementedError)
     end
 
-    # @private
-    # @return [Array<String>]
-    def jsi_object_group_text
-      if jsi_schemas && jsi_schemas.any?
-        class_n_schemas = -"#{self.class} (#{jsi_schemas.map { |s| s.jsi_schema_module.name_from_ancestor || s.jsi_ptr.uri }.join(' ')})"
-      else
-        class_n_schemas = self.class.to_s
-      end
-      [
-        class_n_schemas,
-        is_a?(Schema::MetaSchema) ? "Meta-Schema" : is_a?(Schema) ? "Schema" : nil,
-        *(jsi_node_content.respond_to?(:jsi_object_group_text) ? jsi_node_content.jsi_object_group_text : nil),
-      ].compact.freeze
+    protected def jsi_dynamic_root_instantiate(**kw)
+      # self is a resource root being instantiated with overridden dynamic scope
+      #chkbug fail unless jsi_ptr.root? # jsi_schema_resource_ancestors not tracked
+      to_initialize_finish(MetaSchemaNode.new(**kw))
     end
 
     # see {Util::Private::FingerprintHash}
     # @api private
     def jsi_fingerprint
-      {class: self.class, jsi_document: jsi_document}.merge(our_initialize_params).freeze
+      jsi_fingerprint_no_schemas
     end
 
     protected
@@ -213,61 +258,83 @@ module JSI
     private
 
     def jsi_memomaps_initialize
-      if jsi_ptr.root?
+      if equal?(@jsi_root_node)
         @root_descendent_node_map = jsi_memomap(&method(:jsi_root_descendent_node_compute))
       else
         @root_descendent_node_map = @jsi_root_node.root_descendent_node_map
       end
     end
 
-    # note: does not include jsi_root_node
-    def our_initialize_params
-      {
-        jsi_ptr: jsi_ptr,
-        schema_implementation_modules: schema_implementation_modules,
-        metaschema_root_ptr: metaschema_root_ptr,
-        root_schema_ptr: root_schema_ptr,
-        jsi_schema_base_uri: jsi_schema_base_uri,
-        jsi_schema_registry: jsi_schema_registry,
-        jsi_content_to_immutable: jsi_content_to_immutable,
-      }.freeze
-    end
-
-    # note: not for root node
-    def new_node(**params)
-      MetaSchemaNode.new(jsi_document, jsi_root_node: jsi_root_node, **our_initialize_params, **params)
-    end
-
     def jsi_root_descendent_node_compute(ptr: )
-      #chkbug raise(Bug) unless jsi_ptr.root?
+      # note: self is jsi_root_node
+      #chkbug fail(Bug) unless equal?(jsi_root_node)
       if ptr.root?
         self
       else
-        new_node(
+        MetaSchemaNode.new(
+          jsi_document: jsi_document,
           jsi_ptr: ptr,
-          jsi_schema_base_uri: jsi_resource_ancestor_uri,
+          jsi_base_uri: jsi_next_base_uri,
+          jsi_schema_resource_ancestors: is_a?(Schema) ? jsi_subschema_resource_ancestors : Util::EMPTY_ARY,
+          # since MSN only supports document root as jsi_resource_root, and jsi_next_schema_dynamic_anchor_map
+          # is only passed to descendents that are resource roots, that is not used here.
+          jsi_schema_dynamic_anchor_map: jsi_schema_dynamic_anchor_map,
+          jsi_root_node: jsi_root_node,
         )
       end
     end
 
-    # @param bootstrap_schemas [Enumerable<BootstrapSchema>]
-    # @return [SchemaSet<MetaSchemaNode>]
-    def bootstrap_schemas_to_msn(bootstrap_schemas)
-      SchemaSet.new(bootstrap_schemas) do |bootstrap_schema|
-        if bootstrap_schema.jsi_ptr == jsi_ptr
-          self
-        elsif bootstrap_schema.jsi_ptr.root?
-          @jsi_root_node
+    # @param ptr [Ptr]
+    # @return [MetaSchemaNode]
+    protected def root_descendent_node(ptr)
+      to_initialize_finish(@root_descendent_node_map[
+        ptr: ptr.resolve_against(jsi_document),
+      ])
+    end
+
+    def to_initialize_finish(node)
+      if @initialize_finished
+        node.jsi_initialize_finish
+      else
+        @to_initialize_finish.push(node)
+      end
+
+      node
+    end
+
+    # @param bootstrap_schema [MetaSchemaNode::BootstrapSchema]
+    # @return [MetaSchemaNode]
+    def bootstrap_schema_to_msn(bootstrap_schema)
+      dynamic_anchor_map = Schema::DynamicAnchorMap::EMPTY
+      bootstrap_schema.jsi_schema_dynamic_anchor_map.each do |anchor, (bootstrap_anchor_root, anchor_ptrs)|
+        msn_anchor_root = bootstrap_schema_to_msn(bootstrap_anchor_root)
+        dynamic_anchor_map = dynamic_anchor_map.merge({
+          anchor => [msn_anchor_root, anchor_ptrs].freeze,
+        }).freeze
+      end
+
+      if bootstrap_schema.jsi_document.equal?(jsi_document)
+        root_descendent_node(bootstrap_schema.jsi_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
+      else
+        jsi_registry || raise(ResolutionError, "no jsi_registry")
+        bootstrap_resource = bootstrap_schema.jsi_resource_root
+        resource_uri = bootstrap_resource.jsi_resource_uri || raise(ResolutionError, "no URI: #{bootstrap_resource}")
+        if jsi_registry.registered?(resource_uri)
+          resource = jsi_registry.find(resource_uri)
+          relative_ptr = bootstrap_schema.jsi_ptr.relative_to(bootstrap_resource.jsi_ptr)
+          resource.jsi_descendent_node(relative_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
         else
-          new_node(
-            jsi_ptr: bootstrap_schema.jsi_ptr,
-            jsi_schema_base_uri: bootstrap_schema.jsi_schema_base_uri,
-          )
+          root = to_initialize_finish(MetaSchemaNode.new(
+            jsi_document: bootstrap_schema.jsi_document,
+            jsi_ptr: Ptr[],
+            jsi_base_uri: nil,
+            # this seems like the best dynamic_anchor_map to pass
+            jsi_schema_dynamic_anchor_map: dynamic_anchor_map.without_node(nil, document: bootstrap_schema.jsi_document, ptr: Ptr[], registry: jsi_registry),
+            jsi_conf: jsi_conf,
+          ))
+          root.jsi_descendent_node(bootstrap_schema.jsi_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
         end
       end
     end
   end
-
-  # @deprecated after v0.7.0, alias of {MetaSchemaNode}
-  MetaschemaNode = MetaSchemaNode
 end

data/lib/jsi/ptr.rb

@@ -13,7 +13,7 @@ module JSI
       end
 
       # raised when a pointer refers to a path in a document that could not be resolved
-      class ResolutionError < Error
+      class ResolutionError < JSI::ResolutionError
       end
 
       POS_INT_RE = /\A[1-9]\d*\z/
@@ -61,9 +61,9 @@ module JSI
       #     => JSI::Ptr["foo bar"]
       #
       # Note: A fragment does not include a leading '#'. The string "#/foo" is a URI containing the
-      # fragment "/foo", which should be parsed by `Addressable::URI` before passing to this method, e.g.:
+      # fragment "/foo", which should be parsed by `JSI::URI` before passing to this method, e.g.:
       #
-      #     JSI::Ptr.from_fragment(Addressable::URI.parse("#/foo").fragment)
+      #     JSI::Ptr.from_fragment(JSI::URI["#/foo"].fragment)
       #     => JSI::Ptr["foo"]
       #
       # @param fragment [String] a fragment containing a pointer
@@ -71,7 +71,7 @@ module JSI
       # @raise [JSI::Ptr::PointerSyntaxError] when the fragment does not contain a pointer with
       #   valid pointer syntax
       def self.from_fragment(fragment)
-        from_pointer(Addressable::URI.unescape(fragment))
+        from_pointer(URI.unescape(fragment))
       end
 
       # parse a pointer string and instantiate as a JSI::Ptr
@@ -129,6 +129,24 @@ module JSI
         res
       end
 
+      # Resolves each token of this pointer in `document`, in particular resolving strings indicating
+      # array indices to integers.
+      # @param document [Object]
+      # @return [Ptr]
+      def resolve_against(document)
+        return(self) if tokens.empty?
+        node = document
+        resolved_tokens = nil
+        tokens.each_with_index do |token, i|
+          resolved_token, node = node_subscript_token_child(node, token)
+          next if resolved_token.equal?(token)
+          resolved_tokens ||= tokens.dup
+          resolved_tokens[i] = resolved_token
+        end
+        return(self) if !resolved_tokens
+        Ptr.new(resolved_tokens.freeze)
+      end
+
       # the pointer string representation of this pointer
       # @return [String]
       def pointer
@@ -138,13 +156,13 @@ module JSI
       # the fragment string representation of this pointer
       # @return [String]
       def fragment
-        Addressable::URI.escape(pointer).freeze
+        URI.escape(pointer).freeze
       end
 
       # a URI consisting of a fragment containing this pointer's fragment string representation
-      # @return [Addressable::URI]
+      # @return [URI]
       def uri
-        Addressable::URI.new(fragment: fragment).freeze
+        URI.new(fragment: fragment).freeze
       end
 
       # whether this pointer is empty, i.e. it has no tokens
@@ -175,11 +193,6 @@ module JSI
         tokens == other_ptr.tokens[0...tokens.size]
       end
 
-      # @deprecated
-      def contains?(other_ptr)
-        ancestor_of?(other_ptr)
-      end
-
       # part of this pointer relative to the given ancestor_ptr
       # @return [JSI::Ptr]
       # @raise [JSI::Ptr::Error] if the given ancestor_ptr is not an ancestor of this pointer
@@ -196,6 +209,7 @@ module JSI
       # @return [JSI::Ptr]
       def +(ptr)
         if ptr.is_a?(Ptr)
+          return(ptr) if tokens.empty?
           ptr_tokens = ptr.tokens
         elsif ptr.respond_to?(:to_ary)
           ptr_tokens = ptr
@@ -210,10 +224,12 @@ module JSI
       # @return [JSI::Ptr]
       # @raise [ArgumentError] if n is not between 0 and the size of our tokens
       def take(n)
+        return(EMPTY) if n == 0
+        return(self) if n == tokens.size
         unless n.is_a?(Integer) && n >= 0 && n <= tokens.size
           raise(ArgumentError, "n not in range (0..#{tokens.size}): #{n.inspect}")
         end
-        n == tokens.size ? self : Ptr.new(tokens.take(n).freeze)
+        Ptr.new(tokens.take(n).freeze)
       end
 
       # appends the given token to this pointer's tokens and returns the result
@@ -249,13 +265,13 @@ module JSI
           cdr = tokens.size == 1 ? EMPTY : Ptr.new(tokens[1..-1].freeze)
           token, document_child = node_subscript_token_child(document, car)
           modified_document_child = cdr.modified_document_copy(document_child, &block)
-          if modified_document_child.object_id == document_child.object_id
+          if modified_document_child.equal?(document_child)
             document
           else
             modified_document = document.respond_to?(:[]=) ? document.dup :
               document.respond_to?(:to_hash) ? document.to_hash.dup :
               document.respond_to?(:to_ary) ? document.to_ary.dup :
-              raise(Bug) # not possible; node_subscript_token_child would have raised
+              fail(Bug) # not possible; node_subscript_token_child would have raised
             modified_document[token] = modified_document_child
             modified_document
           end
@@ -284,6 +300,7 @@ module JSI
       private
 
       def node_subscript_token_child(value, token, *a, **kw)
+        token = token.jsi_node_content if token.is_a?(Schema::SchemaAncestorNode)
         if value.respond_to?(:to_ary)
           if token.is_a?(String) && (token == '0' || token =~ POS_INT_RE)
             token = token.to_i