jsi-dev 0.0.8 → 0.0.10

data/lib/jsi/base.rb

@@ -10,52 +10,158 @@ module JSI
   # These subclasses are generally intended to be ignored by applications using this library - the purpose
   # they serve is to include modules relevant to the instance. The modules these classes include are:
   #
-  # - the {Schema#jsi_schema_module} of each schema which describes the instance
+  # - the {SchemaModule JSI Schema Module} of each schema which describes the instance
   # - {Base::HashNode}, {Base::ArrayNode}, or {Base::StringNode} if the instance is
   #   a hash/object, array, or string
+  # - {Base::Immutable} or {Base::Mutable}
   # - Modules defining accessor methods for property names described by the schemas
   class Base
     autoload :ArrayNode, 'jsi/base/node'
     autoload :HashNode, 'jsi/base/node'
     autoload :StringNode, 'jsi/base/node'
+    autoload(:Mutable, 'jsi/base/mutability')
+    autoload(:Immutable, 'jsi/base/mutability')
 
     include Schema::SchemaAncestorNode
+    include(Util::Pretty)
 
     # An exception raised when attempting to access a child of a node which cannot have children.
     # A complex node can have children, a simple node cannot.
     class SimpleNodeChildError < StandardError
     end
 
+    class ChildNotPresent < StandardError
+    end
+
+    conf_attrs = {
+      root_uri:                               {fingerprint: true },
+      registry:                               {fingerprint: true },
+      application_collect_evaluated_validate: {fingerprint: false},
+      reinstantiate_nonschemas:               {fingerprint: false},
+      after_initialize:                       {fingerprint: false},
+      child_as_jsi:                           {fingerprint: false},
+      child_use_default:                      {fingerprint: false},
+      to_immutable:                           {fingerprint: false},
+    }.freeze
+    Conf = Struct.subclass(*conf_attrs.keys)
+    class Conf end
+    Conf::ATTRS = conf_attrs
+
+    # Configuration, shared across all nodes of a document. A JSI's {Base#jsi_conf}.
+    #
+    # Configuration parameters are set from `**conf_kw` params passed to {SchemaSet#new_jsi #new_jsi},
+    # {Schema::MetaSchema#new_schema #new_schema} and related methods.
+    #
+    # @!attribute root_uri
+    #   A URI identifying the document root resource.
+    #   References (e.g. a schema `$ref`) can resolve the resource with this URI.
+    #
+    #   It is rare that this needs to be specified. Most resources that would be
+    #   referenced are schemas that use the `$id` keyword to specify their URI.
+    #   However, there are cases when a resource may be referenced using a retrieval URI
+    #   that does not match the resource's `$id`, and `root_uri` enables resolution.
+    #   @return [URI, nil]
+    # @!attribute registry
+    #   The registry from which references are resolved.
+    #   For schemas (or documents containing schemas), this is mainly used with `$ref` values.
+    #   It is unused in instances that do not contain schemas.
+    #
+    #   Default: {JSI.registry}
+    #   @return [Registry, nil]
+    # @!attribute application_collect_evaluated_validate
+    #   Shall schema application perform validation when collecting child evaluation
+    #   (for `unevaluatedProperties`, `unevaluatedItems`)?
+    #
+    #   A child should not be considered evaluated by a schema when it fails to validate[^1].
+    #   This means that `unevaluatedItems` or `unevaluatedProperties` should
+    #   only apply to a child if no other applicator schema validates the child.
+    #   The computational cost of this validation is significant, however, and may be unacceptable for performance.
+    #
+    #   Set to `true`, child evaluation will perform validation, and `unevaluated*` will applicate
+    #   correctly, at some cost in CPU time.
+    #
+    #   Set to `false`, a child will be considered evaluated when a child applicator schema applies to it,
+    #   regardless of validity, which will result in an `unevaluated*` schema incorrectly failing to
+    #   applicate when the child is not valid.
+    #
+    #   The default is false. It is expected that application of `unevaluated*` schemas to such children
+    #   is not typically relied on, so validation is not typically worth the cost of its computation.
+    #
+    #   [^1]: (ref: the JSON Schema spec states, "Schema objects that produce a false assertion result MUST
+    #   NOT produce any annotation results, whether from their own keywords or from keywords in subschemas.")
+    #
+    #   Default: false
+    #   @return [Boolean]
+    # @!attribute reinstantiate_nonschemas
+    #   _private, not officially supported_. whether Schema#resource_root_subschema reinstantiates.
+    # @!attribute after_initialize
+    #   _EXPERIMENTAL_ - a callback that is called with each JSI node in the document after the node is initialized.
+    #   @return [#call, nil]
+    # @!attribute child_as_jsi
+    #   Default value for {Base#jsi_as_child_default_as_jsi}.
+    #   @return [Boolean]
+    # @!attribute child_use_default
+    #   Default value for {Base#jsi_child_use_default_default}.
+    #   @return [Boolean]
+    # @!attribute to_immutable
+    #   A callable that transforms given instance content to an immutable (i.e. deeply frozen) object equal to it.
+    #
+    #   Used when instantiating immutable JSIs and modified copies of them, so their content is immutable.
+    #
+    #   If the instantiated JSI will be mutable, this is not used.
+    #
+    #   Though not recommended, this may be nil with immutable JSIs if the instance content is otherwise
+    #   guaranteed to be immutable, as well as any modified copies of the instance.
+    #
+    #   Default: {DEFAULT_CONTENT_TO_IMMUTABLE}
+    #   @return [#call, nil]
+    class Conf
+      def initialize(
+          root_uri: nil,
+          registry: JSI.registry,
+          application_collect_evaluated_validate: false,
+          child_as_jsi: false,
+          child_use_default: false,
+          to_immutable: DEFAULT_CONTENT_TO_IMMUTABLE,
+          **kw
+      )
+        super(
+          root_uri: Util.uri(root_uri, nnil: false, yabs: true),
+          registry: registry,
+          application_collect_evaluated_validate: application_collect_evaluated_validate,
+          child_as_jsi: child_as_jsi,
+          child_use_default: child_use_default,
+          to_immutable: to_immutable,
+          **kw,
+        )
+        freeze
+      end
+
+      # @private
+      # @return [Hash]
+      def for_fingerprint
+        to_h.select { |k, _| self.class::ATTRS.fetch(k).fetch(:fingerprint) }.freeze
+      end
+    end
+
     class << self
       # A string indicating the schema module name
       # and/or schema URI of each schema the class represents.
       # @return [String]
       def inspect
-        if !respond_to?(:jsi_class_schemas)
-          super
-        else
-          schema_names = jsi_class_schemas.map do |schema|
-            mod_name = schema.jsi_schema_module.name_from_ancestor
-            if mod_name && schema.schema_absolute_uri
-              "#{mod_name} <#{schema.schema_absolute_uri}>"
-            elsif mod_name
-              mod_name
-            elsif schema.schema_uri
-              schema.schema_uri.to_s
-            else
-              schema.jsi_ptr.uri.to_s
-            end
-          end
-
-          if schema_names.empty?
-            "(JSI Schema Class for 0 schemas)"
-          else
-            -"(JSI Schema Class: #{schema_names.join(' + ')})"
-          end
+        return super unless respond_to?(:jsi_class_schemas)
+        schema_names = jsi_class_schemas.map do |schema|
+          mod_name = schema.jsi_schema_module_name_from_ancestor
+          next "#{mod_name} <#{schema.jsi_resource_uri}>" if mod_name && schema.jsi_resource_uri
+          mod_name || "<#{schema.schema_uri || schema.jsi_ptr.uri}>"
         end
+        "(#{[superclass, *schema_names, *jsi_class_includes].join(' + ')})"
+      end
+
+      def to_s
+        inspect
       end
 
-      alias_method :to_s, :inspect
       # A constant name of this class. This is generated from any schema module name or URI of each schema
       # this class represents, or random characters.
       #
@@ -69,9 +175,9 @@ module JSI
         return super unless respond_to?(:jsi_class_schemas)
         alnum = proc { |id| (id % 36**4).to_s(36).rjust(4, '0').upcase }
         schema_names = jsi_class_schemas.map do |schema|
-          named_ancestor_schema, tokens = schema.jsi_schema_module.send(:named_ancestor_schema_tokens)
-          if named_ancestor_schema
-            [named_ancestor_schema.jsi_schema_module.name, *tokens].join('_')
+          named_ancestor, tokens = schema.jsi_schema_module.send(:named_ancestor_tokens)
+          if named_ancestor
+            [named_ancestor.jsi_schema_module_connection.name, *tokens].join('_')
           elsif schema.schema_uri
             schema.schema_uri.to_s
           else
@@ -97,43 +203,53 @@ module JSI
     #
     # this is a private api - users should look elsewhere to instantiate JSIs, in particular:
     #
-    # - {JSI.new_schema} and {Schema::DescribesSchema#new_schema} to instantiate schemas
+    # - {JSI.new_schema} and {Schema::MetaSchema#new_schema} to instantiate schemas
     # - {Schema#new_jsi} to instantiate schema instances
     #
     # @api private
     # @param jsi_document [Object] the document containing the instance
     # @param jsi_ptr [JSI::Ptr] a pointer pointing to the JSI's instance in the document
-    # @param jsi_schema_base_uri [Addressable::URI] see {SchemaSet#new_jsi} param uri
+    # @param jsi_base_uri [URI, nil] see {SchemaSet#new_jsi} param `base_uri`
     # @param jsi_schema_resource_ancestors [Array<JSI::Base + JSI::Schema>]
-    # @param jsi_root_node [JSI::Base] the JSI of the root of the document containing this JSI
-    def initialize(jsi_document,
+    # @param jsi_schema_dynamic_anchor_map [Schema::DynamicAnchorMap]
+    # @param jsi_dynamic_root_map map of (ptr, dynamic_anchor_map) → (Base root node), shared across dynamic root nodes
+    # @param jsi_conf [Base::Conf]
+    # @param jsi_root_node [JSI::Base, nil]
+    def initialize(
+        jsi_document: ,
         jsi_ptr: Ptr[],
         jsi_indicated_schemas: ,
-        jsi_schema_base_uri: nil,
+        jsi_base_uri: nil,
         jsi_schema_resource_ancestors: Util::EMPTY_ARY,
-        jsi_schema_registry: ,
+        jsi_schema_dynamic_anchor_map: Schema::DynamicAnchorMap::EMPTY,
+        jsi_dynamic_root_map: nil,
+        jsi_conf: nil,
         jsi_root_node: nil
     )
-      raise(Bug, "no #jsi_schemas") unless respond_to?(:jsi_schemas)
-
-      super()
-
-      self.jsi_document = jsi_document
-      self.jsi_ptr = jsi_ptr
-      self.jsi_indicated_schemas = jsi_indicated_schemas
-      self.jsi_schema_base_uri = jsi_schema_base_uri
+      #chkbug fail(Bug, "no #jsi_schemas") unless respond_to?(:jsi_schemas)
+
+      #chkbug fail(Bug) if !jsi_root_node ^ jsi_conf
+      @jsi_conf = jsi_conf = jsi_conf || jsi_root_node.jsi_conf
+      @jsi_document = jsi_document
+      #chkbug fail(Bug) unless jsi_ptr.is_a?(Ptr)
+      #chkbug fail(Bug) unless jsi_ptr.resolve_against(jsi_document).equal?(jsi_ptr)
+      @jsi_ptr = jsi_ptr
+      #chkbug fail(Bug) unless jsi_indicated_schemas.is_a?(SchemaSet)
+      @jsi_indicated_schemas = jsi_indicated_schemas
+      self.jsi_base_uri = jsi_base_uri
       self.jsi_schema_resource_ancestors = jsi_schema_resource_ancestors
-      self.jsi_schema_registry = jsi_schema_registry
-      if @jsi_ptr.root?
-        raise(Bug, "jsi_root_node specified for root JSI") if jsi_root_node
-        @jsi_root_node = self
-      else
-        raise(Bug, "jsi_root_node is not JSI::Base") if !jsi_root_node.is_a?(JSI::Base)
-        raise(Bug, "jsi_root_node ptr is not root") if !jsi_root_node.jsi_ptr.root?
-        @jsi_root_node = jsi_root_node
-      end
-
+      self.jsi_schema_dynamic_anchor_map = jsi_schema_dynamic_anchor_map
+      #chkbug fail(Bug) if jsi_root_node && jsi_dynamic_root_map
+      @jsi_dynamic_root_map = jsi_dynamic_root_map || (jsi_root_node ? jsi_root_node.jsi_dynamic_root_map : jsi_memomap(&method(:jsi_dynamic_root_compute)))
+      @jsi_root_node = jsi_root_node || self
+      @root_rel_ptr = @jsi_ptr.relative_to(@jsi_root_node.jsi_ptr)
+
+      # @memos does not freeze if/when the node freezes
+      @memos = {}
       jsi_memomaps_initialize
+      jsi_mutability_initialize
+
+      super()
 
       if jsi_instance.is_a?(JSI::Base)
         raise(TypeError, "a JSI::Base instance must not be another JSI::Base. received: #{jsi_instance.pretty_inspect.chomp}")
@@ -142,7 +258,7 @@ module JSI
 
     # @!method jsi_schemas
     #   The set of schemas that describe this instance.
-    #   These are the applicator schemas that apply to this instance, the result of inplace application
+    #   These are the applicator schemas that apply to this instance, the result of in-place application
     #   of our {#jsi_indicated_schemas}.
     #   @return [JSI::SchemaSet]
     # note: defined on subclasses by JSI::SchemaClasses.class_for_schemas
@@ -155,25 +271,41 @@ module JSI
     # @return [JSI::Ptr]
     attr_reader :jsi_ptr
 
-    # the JSI at the root of this JSI's document
+    # See {SchemaSet#new_jsi} param `registry`
+    # @return [Registry, nil]
+    def jsi_registry
+      jsi_conf.registry
+    end
+
+    attr_reader(:jsi_dynamic_root_map)
+    protected(:jsi_dynamic_root_map)
+
+    # @return [Base::Conf]
+    attr_reader(:jsi_conf)
+
+    # The root ancestor of this node. This is typically the document root, though
+    # it can be a different resource root when dynamic scope is overridden.
     # @return [JSI::Base]
     attr_reader :jsi_root_node
 
     # the content of this node in our {#jsi_document} at our {#jsi_ptr}. the same as {#jsi_instance}.
     def jsi_node_content
-      content = jsi_ptr.evaluate(jsi_document)
-      content
+      # stub method for doc, overridden by Mutable/Immutable
     end
 
-    # the JSON schema instance this JSI represents - the underlying JSON data used to instantiate this JSI
-    alias_method :jsi_instance, :jsi_node_content
+    # The JSON schema instance this JSI represents - the underlying JSON data used to instantiate this JSI.
+    # The same as {#jsi_node_content} - 'node content' is usually preferable terminology, to avoid
+    # ambiguity in the heavily overloaded term 'instance'.
+    def jsi_instance
+      jsi_node_content
+    end
 
-    # the schemas indicated as describing this instance, prior to inplace application.
+    # The schemas indicated as describing this instance, prior to in-place application.
     #
-    # this is different from {#jsi_schemas}, which are the inplace applicator schemas
+    # This is different from {#jsi_schemas}, which are the in-place applicator schemas
     # which describe this instance. for most purposes, `#jsi_schemas` is more relevant.
     #
-    # `jsi_indicated_schemas` does not include inplace applicator schemas, such as the
+    # `jsi_indicated_schemas` does not include in-place applicator schemas, such as the
     # subschemas of `allOf`, whereas `#jsi_schemas` does.
     #
     # this does include indicated schemas which do not apply themselves, such as `$ref`
@@ -192,7 +324,22 @@ module JSI
     # @yield [JSI::Base] each descendent node, starting with self
     # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
     def jsi_each_descendent_node(propertyNames: false, &block)
-      return to_enum(__method__, propertyNames: propertyNames) unless block
+      unless block
+        return to_enum(__method__, propertyNames: propertyNames) do
+          # size
+          Util.ycomb do |rec|
+            proc do |node|
+              if node.respond_to?(:to_hash)
+                node.to_hash.inject(1) { |c, (k, child)| c + rec[child] + (propertyNames ? rec[k] : 0) }
+              elsif node.respond_to?(:to_ary)
+                node.to_ary.inject(1) { |c, child| c + rec[child] }
+              else
+                1
+              end
+            end
+          end[jsi_node_content]
+        end
+      end
 
       yield self
 
@@ -203,12 +350,38 @@ module JSI
       end
 
       jsi_each_child_token do |token|
-        jsi_child(token, as_jsi: true).jsi_each_descendent_node(propertyNames: propertyNames, &block)
+        jsi_child_node(token).jsi_each_descendent_node(propertyNames: propertyNames, &block)
       end
 
       nil
     end
 
+    # yields each descendent of this node that is a JSI Schema
+    # @yield [Base + Schema]
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def jsi_each_descendent_schema(&block)
+      return(to_enum(__method__)) unless block_given?
+
+      # note: this never yields self; if self is a Schema, Schema#jsi_each_descendent_schema overrides this method
+      jsi_each_child_token do |token|
+        jsi_child_node(token).jsi_each_descendent_schema(&block)
+      end
+    end
+
+    # yields each descendent of this node within the same resource that is a Schema
+    # @yield [Schema]
+    def jsi_each_descendent_schema_same_resource(&block)
+      return(to_enum(__method__)) unless block_given?
+
+      jsi_each_child_token do |token|
+        child = jsi_child_node(token)
+        if !child.jsi_is_resource_root?
+          # note: if child is a Schema, Schema#jsi_each_descendent_schema_same_resource overrides Base
+          child.jsi_each_descendent_schema_same_resource(&block)
+        end
+      end
+    end
+
     # recursively selects descendent nodes of this JSI, returning a modified copy of self containing only
     # descendent nodes for which the given block had a true-ish result.
     #
@@ -222,7 +395,7 @@ module JSI
         if jsi_array? || jsi_hash?
           res = instance.class.new
           jsi_each_child_token do |token|
-            v = jsi_child(token, as_jsi: true)
+            v = jsi_child_node(token)
             if yield(v)
               res_v = v.jsi_select_descendents_node_first(&block).jsi_node_content
               if jsi_array?
@@ -252,7 +425,7 @@ module JSI
         if jsi_array? || jsi_hash?
           res = instance.class.new
           jsi_each_child_token do |token|
-            v = jsi_child(token, as_jsi: true).jsi_select_descendents_leaf_first(&block)
+            v = jsi_child_node(token).jsi_select_descendents_leaf_first(&block)
             if yield(v)
               res_v = v.jsi_node_content
               if jsi_array?
@@ -269,24 +442,24 @@ module JSI
       end
     end
 
-    # an array of JSI instances above this one in the document.
+    # JSI nodes above this one in the document.
     #
     # @return [Array<JSI::Base>]
     def jsi_parent_nodes
-      parent = jsi_root_node
-
-      jsi_ptr.tokens.map do |token|
-        parent.tap do
-          parent = parent[token, as_jsi: true]
-        end
-      end.reverse!.freeze
+      parent_nodes = []
+      ptr = @root_rel_ptr
+      while !ptr.root?
+        ptr = ptr.parent
+        parent_nodes.push(jsi_root_node.jsi_descendent_node(ptr))
+      end
+      parent_nodes.freeze
     end
 
     # the immediate parent of this JSI. nil if there is no parent.
     #
     # @return [JSI::Base, nil]
     def jsi_parent_node
-      jsi_ptr.root? ? nil : jsi_root_node.jsi_descendent_node(jsi_ptr.parent)
+      @root_rel_ptr.root? ? nil : jsi_root_node.jsi_descendent_node(@root_rel_ptr.parent)
     end
 
     # ancestor JSI instances from this node up to the root. this node itself is always its own first ancestor.
@@ -297,8 +470,8 @@ module JSI
       ancestor = jsi_root_node
       ancestors << ancestor
 
-      jsi_ptr.tokens.each do |token|
-        ancestor = ancestor[token, as_jsi: true]
+      @root_rel_ptr.tokens.each do |token|
+        ancestor = ancestor.jsi_child_node(token)
         ancestors << ancestor
       end
       ancestors.reverse!.freeze
@@ -309,11 +482,11 @@ module JSI
     # @param ptr [JSI::Ptr, #to_ary]
     # @return [JSI::Base]
     def jsi_descendent_node(ptr)
-      descendent = Ptr.ary_ptr(ptr).evaluate(self, as_jsi: true)
-      descendent
+      tokens = Ptr.ary_ptr(ptr).resolve_against(jsi_node_content).tokens
+      tokens.inject(self, &:jsi_child_node)
     end
 
-    # A shorthand alias for {#jsi_descendent_node}.
+    # The descendent node at the given {Ptr}, token array, or pointer string.
     #
     # Note that, though more convenient to type, using an operator whose meaning may not be intuitive
     # to a reader could impair readability of code.
@@ -322,13 +495,14 @@ module JSI
     #
     #     my_jsi / ['foo', 'bar']
     #     my_jsi / %w(foo bar)
+    #     my_jsi / '/foo/bar'
     #     my_schema / JSI::Ptr['additionalProperties']
     #     my_schema / %w(properties foo items additionalProperties)
     #
-    # @param (see #jsi_descendent_node)
+    # @param ptr [JSI::Ptr, #to_ary, #to_str]
     # @return (see #jsi_descendent_node)
     def /(ptr)
-      jsi_descendent_node(ptr)
+      jsi_descendent_node(ptr.respond_to?(:to_str) ? Ptr.from_pointer(ptr) : ptr)
     end
 
     # yields each token (array index or hash key) identifying a child node.
@@ -350,11 +524,20 @@ module JSI
     #
     # @param token [String, Integer]
     # @return [Boolean]
-    def jsi_child_token_in_range?(token)
+    def jsi_child_token_present?(token)
       # note: overridden by Base::HashNode, Base::ArrayNode
       false
     end
 
+    # @api private
+    # @return [nil]
+    def jsi_child_ensure_present(token)
+      if !jsi_child_token_present?(token)
+        raise(ChildNotPresent, -"token does not identify a child that is present: #{token.inspect}\nself = #{pretty_inspect.chomp}")
+      end
+      nil
+    end
+
     # The child of the {#jsi_node_content} identified by the given token,
     # or `nil` if the token does not identify an existing child.
     #
@@ -369,27 +552,37 @@ module JSI
     end
 
     # A child JSI node, or the child of our {#jsi_instance}, identified by the given token.
-    # The token must identify an existing child; behavior if the child does not exist is undefined.
     #
     # @param token (see Base#[])
     # @param as_jsi (see Base#[])
     # @return [JSI::Base, Object]
+    # @raise [Base::ChildNotPresent]
     def jsi_child(token, as_jsi: )
+      jsi_child_as_jsi(jsi_child_node(token), as_jsi)
+    end
+    private :jsi_child # internals for #[] but idk, could be public
+
+    # @param token An array index or Hash/object property name identifying a present child of this node
+    # @return [JSI::Base]
+    # @raise [Base::ChildNotPresent]
+    def jsi_child_node(token)
+      @child_node_by_token_map[token: token]
+    end
+
+    private def jsi_child_node_by_token_compute(token: )
+      jsi_child_ensure_present(token)
+
       child_content = jsi_node_content_child(token)
 
       child_indicated_schemas = @child_indicated_schemas_map[token: token, content: jsi_node_content]
       child_applied_schemas = @child_applied_schemas_map[token: token, child_indicated_schemas: child_indicated_schemas, child_content: child_content]
-
-      jsi_child_as_jsi(child_content, child_applied_schemas, as_jsi) do
-        @child_node_map[
+      @child_node_map[
           token: token,
           child_indicated_schemas: child_indicated_schemas,
           child_applied_schemas: child_applied_schemas,
           includes: SchemaClasses.includes_for(child_content),
-        ]
-      end
+      ]
     end
-    private :jsi_child # internals for #[] but idk, could be public
 
     # A default value for a child of this node identified by the given token, if schemas describing
     # that child define a default value.
@@ -410,41 +603,42 @@ module JSI
 
       defaults = Set.new
       child_applied_schemas.each do |child_schema|
-        if child_schema.keyword?('default')
-          defaults << child_schema.jsi_node_content['default']
-        end
+        defaults.merge(child_schema.dialect_invoke_each(:default))
       end
 
       if defaults.size == 1
         # use the default value
-        jsi_child_as_jsi(defaults.first, child_applied_schemas, as_jsi) do
+        default_child_node =
           jsi_modified_copy do |i|
             i.dup.tap { |i_dup| i_dup[token] = defaults.first }
-          end[token, as_jsi: true]
-        end
+          end.jsi_child_node(token)
+        jsi_child_as_jsi(default_child_node, as_jsi)
       else
         child_content
       end
     end
     private :jsi_default_child # internals for #[] but idk, could be public
 
-    # subscripts to return a child value identified by the given token.
+    # Returns a child or children identified by param `token`.
+    #
+    # @param token [String, Integer, Range, Object] Identifies the child or children to return.
+    #   Typically an array index or hash key (JSON object property name) of the instance.
+    #
+    #   For an array instance, this may also be a Range (in which case an Array of children is returned)
+    #   or a negative index; these behave as Array#[] does.
+    # @param as_jsi [:auto, true, false] (default is `:auto` or {Base::Conf#child_as_jsi conf child_as_jsi})
     #
-    # @param token [String, Integer, Object] an array index or hash key (JSON object property name)
-    #   of the instance identifying the child value
-    # @param as_jsi [:auto, true, false] (default is `:auto`)
     #   Whether to return the child as a JSI. One of:
     #
     #   - `:auto`: By default a JSI will be returned when either:
     #
-    #     - the result is a complex value (responds to #to_ary or #to_hash)
-    #     - the result is a schema (including true/false schemas)
+    #     - the child is an array or hash
+    #     - the child is a schema (including true/false schemas)
     #
     #     The plain content is returned when it is a simple type.
     #
-    #   - true: the result value will always be returned as a JSI. the {#jsi_schemas} of the result may be
-    #     empty if no schemas describe the instance.
-    #   - false: the result value will always be the plain instance.
+    #   - true: the result will always be returned as a JSI.
+    #   - false: the result will always be the node's content.
     #
     #   note that nil is returned (regardless of as_jsi) when there is no value to return because the token
     #   is not a hash key or array index of the instance and no default value applies.
@@ -461,15 +655,26 @@ module JSI
     #
     #   if the child instance's schemas do not indicate a single default value (that is, if zero or multiple
     #   defaults are specified across those schemas), nil is returned.
-    #   (one exception is when this JSI's instance is a Hash with a default or default_proc, which has
-    #   unspecified behavior.)
-    # @return [JSI::Base, Object, nil] the child value identified by the subscript token
+    # @return [Base, Object, Array, nil] the child or children identified by `token`
     def [](token, as_jsi: jsi_child_as_jsi_default, use_default: jsi_child_use_default_default)
+      raise(BlockGivenError) if block_given?
       # note: overridden by Base::HashNode, Base::ArrayNode
       jsi_simple_node_child_error(token)
     end
 
+    # When accessing this node as a child (from a parent's {#[]} or a property reader), should the result
+    # by default be a JSI node (this node), or its node content?
+    # This default may be overridden using the `as_jsi` parameter calling the parent's {#[]}.
+    # {Base::Conf Configurable} using {Base::Conf#child_as_jsi `child_as_jsi`}.
+    # @return [Boolean]
+    def jsi_as_child_default_as_jsi
+      # base default is false, for simple types. overridden by complex types (HashNode, ArrayNode), Schema, and others.
+      jsi_conf.child_as_jsi
+    end
+
     # The default value for the param `as_jsi` of {#[]}, controlling whether a child is returned as a JSI instance.
+    # @deprecated after v0.8. This is the parent node's preference whether its children are returned as JSIs, but it
+    #   is better for a child to indicate whether it should be a JSI by overriding {#jsi_as_child_default_as_jsi}.
     # @return [:auto, true, false] a valid value of the `as_jsi` param of {#[]}
     def jsi_child_as_jsi_default
       :auto
@@ -477,33 +682,28 @@ module JSI
 
     # The default value for the param `use_default` of {#[]}, controlling whether a schema default value is
     # returned when a token refers to a child that is not in the document.
+    # {Base::Conf Configurable} using {Base::Conf#child_use_default `child_use_default`}.
     # @return [true, false] a valid value of the `use_default` param of {#[]}
     def jsi_child_use_default_default
-      false
+      jsi_conf.child_use_default
     end
 
-    # assigns the subscript of the instance identified by the given token to the given value.
-    # if the value is a JSI, its instance is assigned instead of the JSI value itself.
+    # Assigns a child identified by the given token to the given value.
+    # If the given value is a JSI node, its content is used; its {#jsi_schemas} are not.
     #
-    # @param token [String, Integer, Object] token identifying the subscript to assign
+    # @param token [String, Integer, Object] token identifying the child to assign
     # @param value [JSI::Base, Object] the value to be assigned
     def []=(token, value)
       unless jsi_array? || jsi_hash?
         jsi_simple_node_child_error(token)
       end
       if value.is_a?(Base)
-        self[token] = value.jsi_instance
+        self[token] = value.jsi_node_content
       else
-        jsi_instance[token] = value
+        jsi_node_content[token] = value
       end
     end
 
-    # the set of JSI schema modules corresponding to the schemas that describe this JSI
-    # @return [Set<Module>]
-    def jsi_schema_modules
-      Util.ensure_module_set(jsi_schemas.map(&:jsi_schema_module))
-    end
-
     # Is this JSI described by the given schema (or schema module)?
     #
     # @param schema [Schema, SchemaModule]
@@ -512,12 +712,18 @@ module JSI
       if schema.is_a?(Schema)
         jsi_schemas.include?(schema)
       elsif schema.is_a?(SchemaModule)
-        jsi_schema_modules.include?(schema)
+        jsi_schemas.include?(schema.schema)
       else
         raise(TypeError, "expected a Schema or Schema Module; got: #{schema.pretty_inspect.chomp}")
       end
     end
 
+    # Is this a JSI Schema?
+    # @return [Boolean]
+    def jsi_is_schema?
+      false
+    end
+
     # yields the content of this JSI's instance. the block must result in
     # a modified copy of the yielded instance (not modified in place, which would alter this JSI
     # as well) which will be used to instantiate and return a new JSI with the modified content.
@@ -527,15 +733,37 @@ module JSI
     #
     # @yield [Object] this JSI's instance. the block should result
     #   in a nondestructively modified copy of this.
-    # @return [JSI::Base subclass] the modified copy of self
-    def jsi_modified_copy(&block)
+    # @return [Base] the modified copy of self
+    def jsi_modified_copy(**conf_kw, &block)
         modified_document = @jsi_ptr.modified_document_copy(@jsi_document, &block)
-        modified_jsi_root_node = @jsi_root_node.jsi_indicated_schemas.new_jsi(modified_document,
-          uri: @jsi_root_node.jsi_schema_base_uri,
-          register: false, # default is already false but this is a place to be explicit
-          schema_registry: jsi_schema_registry,
+
+        conf = jsi_conf.merge(**conf_kw)
+
+        modified_document = conf.to_immutable.call(modified_document) if !jsi_mutable? && conf.to_immutable
+
+        root_content = jsi_root_node.jsi_ptr.evaluate(modified_document)
+
+        root_applied_schemas = SchemaSet.build do |y|
+          c = y.method(:yield) # TODO drop c, just pass y, when all supported Enumerator::Yielder.method_defined?(:to_proc)
+          jsi_root_node.jsi_indicated_schemas.each do |is|
+            is.each_inplace_applicator_schema(root_content, &c)
+          end
+        end
+
+        root_class = JSI::SchemaClasses.class_for_schemas(root_applied_schemas,
+          includes: SchemaClasses.includes_for(root_content),
+          mutable: jsi_mutable?,
         )
-        modified_jsi_root_node.jsi_descendent_node(@jsi_ptr)
+        modified_jsi_root_node = root_class.new(
+          jsi_document: modified_document,
+          jsi_ptr: jsi_root_node.jsi_ptr,
+          jsi_indicated_schemas: jsi_root_node.jsi_indicated_schemas,
+          jsi_base_uri: jsi_root_node.jsi_base_uri,
+          jsi_schema_dynamic_anchor_map: jsi_root_node.jsi_schema_dynamic_anchor_map,
+          jsi_conf: conf,
+        ).send(:jsi_initialized)
+
+        modified_jsi_root_node.jsi_descendent_node(@root_rel_ptr)
     end
 
     # Is the instance an array?
@@ -562,9 +790,15 @@ module JSI
       false
     end
 
+    # Is this JSI mutable?
+    # @return [Boolean]
+    def jsi_mutable?
+      # note: overridden by Base::Mutable / Immutable
+    end
+
     # validates this JSI's instance against its schemas
     #
-    # @return [JSI::Validation::FullResult]
+    # @return [JSI::Validation::Result::Full]
     def jsi_validate
       jsi_indicated_schemas.instance_validate(self)
     end
@@ -575,6 +809,15 @@ module JSI
       jsi_indicated_schemas.instance_valid?(self)
     end
 
+    # Asserts that this JSI is valid against its schemas.
+    # {JSI::Invalid} is raised if it is not.
+    #
+    # @raise [Invalid]
+    # @return [nil]
+    def jsi_valid!
+      jsi_validate.valid!
+    end
+
     # queries this JSI using the [JMESPath Ruby](https://rubygems.org/gems/jmespath) gem.
     # see [https://jmespath.org/](https://jmespath.org/) to learn the JMESPath query language.
     #
@@ -592,41 +835,161 @@ module JSI
       JMESPath.search(expression, self, **runtime_options)
     end
 
-    def dup
-      jsi_modified_copy(&:dup)
+    # The nearest ancestor (including this node) that is a resource root.
+    #
+    # A resource root is a schema with an absolute URI, or the {#jsi_root_node document's root node}
+    # (which might not be a schema and might not have an absolute URI).
+    # @return [Base]
+    def jsi_resource_root
+      super || jsi_root_node
     end
 
-    # a string representing this JSI, indicating any named schemas and inspecting its instance
-    # @return [String]
-    def inspect
-      -"\#<#{jsi_object_group_text.join(' ')} #{jsi_instance.inspect}>"
+    # @private
+    # @return [URI, nil]
+    def jsi_root_uri
+      jsi_conf.root_uri
     end
 
-    alias_method :to_s, :inspect
+    # @private
+    # @return [SchemaModule::Connection]
+    def jsi_schema_module_connection
+      raise(BlockGivenError) if block_given?
+      @memos.fetch(:schema_module_connection) do
+        if is_a?(Schema)
+          raise(TypeError, "mutable schema may not have a schema module: #{self}") if jsi_mutable?
+          module_class = SchemaModule
+        else
+          raise(TypeError, "mutable JSI may not have a SchemaModule::Connection: #{self}") if jsi_mutable?
+          module_class = SchemaModule::Connection
+        end
+        @memos[:schema_module_connection] = module_class.new(self)
+      end
+    end
 
-    # pretty-prints a representation of this JSI to the given printer
+    # @private experimental
+    # a callback to be overridden (remember to call super), called with our #jsi_schema_module_connection when that is created
+    # @param mod [SchemaModule::Connection]
     # @return [void]
+    def jsi_schema_module_connection_created(mod)
+    end
+
+    # @private
+    # @return [Boolean]
+    def jsi_schema_module_connection_defined?
+      @memos.key?(:schema_module_connection)
+    end
+
+    # @param dynamic_anchor_map [Schema::DynamicAnchorMap]
+    # @return [Base]
+    private def jsi_dynamic_root_descendent(dynamic_anchor_map)
+      root = jsi_dynamic_root_map[
+        ptr: jsi_resource_root.jsi_ptr,
+        dynamic_anchor_map: dynamic_anchor_map,
+      ]
+      root.jsi_descendent_node(jsi_ptr.relative_to(jsi_resource_root.jsi_ptr))
+    end
+
+    # This instantiates a new root node (its #jsi_root_node is itself).
+    # When the resource at `ptr` is not the document root, the new root node has the
+    # unusual property that its jsi_ptr is not the root ptr; it is the given `ptr`.
+    # (Calling this a 'root node' is questionable, but that is the name we use.)
+    # From the new root node, no JSI node represents locations in the document above it.
+    # @param ptr [Ptr]
+    # @param dynamic_anchor_map [Schema::DynamicAnchorMap]
+    # @return [Base]
+    private def jsi_dynamic_root_compute(ptr: , dynamic_anchor_map: )
+      # self is always the originally instantiated root node (with jsi_ptr = Ptr[])
+      resource_root = jsi_descendent_node(ptr)
+      if resource_root.jsi_schema_dynamic_anchor_map == dynamic_anchor_map
+        return resource_root
+      end
+
+      resource_root.jsi_dynamic_root_instantiate(
+        jsi_document: resource_root.jsi_document,
+        jsi_ptr: ptr,
+        jsi_base_uri: resource_root.jsi_base_uri,
+        #jsi_schema_resource_ancestors: none (new root),
+        jsi_schema_dynamic_anchor_map: dynamic_anchor_map,
+        jsi_dynamic_root_map: jsi_dynamic_root_map,
+        jsi_conf: resource_root.jsi_conf,
+      )
+    end
+
+    protected def jsi_dynamic_root_instantiate(**kw)
+      # self is a resource root being instantiated with overridden dynamic scope
+      self.class.new(
+        jsi_indicated_schemas: jsi_indicated_schemas,
+        **kw,
+      ).send(:jsi_initialized)
+    end
+
+    # A JSI whose node content is a duplicate of this JSI's (using its #dup).
+    #
+    # Note that immutable JSIs are not made mutable with #dup.
+    # The content's #dup may return an unfrozen copy, but instantiating a modified
+    # copy of this JSI involves transforming the content to immutable again
+    # (using {Base::Conf conf} {Base::Conf#to_immutable to_immutable}).
+    # @return [Base]
+    def dup
+      jsi_modified_copy(&:dup)
+    end
+
+    # Prints a string indicating this JSI's schemas, briefly, and its content.
+    #
+    # If described by a schema with a named schema module, that is shown.
+    # The number of schemas describing this JSI is indicated.
+    #
+    # If this JSI is a simple type, the node's content is inspected; if complex, its children are inspected.
     def pretty_print(q)
-      q.text '#<'
-      q.text jsi_object_group_text.join(' ')
-      q.group_sub {
-        q.nest(2) {
-          q.breakable ' '
+      jsi_pp_object_group(q, jsi_object_group_text) do
           q.pp jsi_instance
-        }
-      }
-      q.breakable ''
-      q.text '>'
+      end
     end
 
     # @private
     # @return [Array<String>]
     def jsi_object_group_text
-      schema_names = jsi_schemas.map { |schema| schema.jsi_schema_module.name_from_ancestor || schema.schema_uri }.compact
+      jsi_schemas = self.jsi_schemas || Util::EMPTY_SET # for debug during MSN initialize, may not be set yet
+      schemas_priorities = jsi_schemas.each_with_index.map do |schema, i|
+        priority = [
+          schema.describes_schema? ? 0 : 1,
+
+          schema.jsi_schema_module_name ?
+            0
+          : schema.jsi_schema_module_name_from_ancestor ?
+            1
+          : schema.jsi_resource_uri ?
+            2
+          : schema.schema_uri ?
+            3
+          : 5,
+
+          !schema.respond_to?(:to_hash) ?
+            # boolean
+            9
+          : schema.empty? ?
+            8
+          : schema.all? { |k, _| k == '$ref' || k == '$dynamicRef' } ?
+            7
+          : 5,
+        ]
+        [priority, i, schema]
+      end.sort
+
+      schema_names = []
+      schemas_priorities.each do |(priority, _idx, schema)|
+        if priority[0] == 0 || (priority == schemas_priorities.first.first && schema_names.size < 2)
+          name = schema.jsi_schema_identifier(required: priority[0] == 0)
+          schema_names << name if name
+        end
+      end
+
       if schema_names.empty?
-        class_txt = "JSI"
+        schemas_txt = -"*#{self.jsi_schemas ? jsi_schemas.size : '?'}"
+      elsif schema_names.size == jsi_schemas.size
+        schemas_txt = -" (#{schema_names.join(' + ')})"
       else
-        class_txt = -"JSI (#{schema_names.join(', ')})"
+        schemas_txt = -" (#{schema_names.join(' + ')} + #{jsi_schemas.size - schema_names.size})"
       end
 
       if (is_a?(ArrayNode) || is_a?(HashNode)) && ![Array, Hash].include?(jsi_node_content.class)
@@ -640,10 +1003,11 @@ module JSI
       end
 
       [
-        class_txt,
-        is_a?(Metaschema) ? "Metaschema" : is_a?(Schema) ? "Schema" : nil,
+        -"JSI#{is_a?(MetaSchemaNode) ? ":MSN" : ""}#{schemas_txt}",
+        is_a?(Schema::MetaSchema) ? "Meta-Schema" : is_a?(Schema) ? "Schema" : nil,
+        is_a?(Schema) && !jsi_schema_dynamic_anchor_map.empty? ? jsi_schema_dynamic_anchor_map.anchor_schemas_identifier : nil,
         *content_txt,
-      ].compact
+      ].compact.freeze
     end
 
     # A structure coerced to JSONifiable types from the instance content.
@@ -656,74 +1020,116 @@ module JSI
     # Calls {Util.to_json} with the instance and any given options.
     # @return [String]
     def to_json(options = {})
-      Util.to_json(jsi_instance, **options)
+      Util.to_json(jsi_instance, options)
+    end
+
+    # Psych/YAML .dump calls this method; dumping a JSI as YAML will dump its instance.
+    # @param coder [Psych::Coder]
+    def encode_with(coder)
+      coder.represent_object(nil, jsi_node_content)
+      nil
     end
 
     # see {Util::Private::FingerprintHash}
     # @api private
     def jsi_fingerprint
       {
-        class: jsi_class,
+        class: JSI::Base,
+        jsi_schemas: jsi_schemas,
         jsi_document: jsi_document,
         jsi_ptr: jsi_ptr,
         # for instances in documents with schemas:
-        jsi_resource_ancestor_uri: jsi_resource_ancestor_uri,
-        # different registries mean references may resolve to different resources so must not be equal
-        jsi_schema_registry: jsi_schema_registry,
-      }
+        jsi_base_uri: jsi_base_uri,
+        jsi_root_uri: jsi_conf.root_uri,
+        # different dynamic anchor map means dynamic references may resolve to different resources so must not be equal
+        jsi_schema_dynamic_anchor_map: jsi_schema_dynamic_anchor_map,
+        **jsi_conf.for_fingerprint,
+      }.freeze
+    end
+
+    # @private
+    def jsi_next_schema_dynamic_anchor_map
+      jsi_schema_dynamic_anchor_map
     end
-    include Util::FingerprintHash
 
     private
 
-    def jsi_memomaps_initialize
-      @child_indicated_schemas_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_indicated_schemas_compute))
-      @child_applied_schemas_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_applied_schemas_compute))
-      @child_node_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_node_compute))
-    end
+    BY_TOKEN = proc { |i| i[:token] }
 
-    def jsi_indicated_schemas=(jsi_indicated_schemas)
-      #chkbug raise(Bug) unless jsi_indicated_schemas.is_a?(SchemaSet)
-      @jsi_indicated_schemas = jsi_indicated_schemas
+    def jsi_memomaps_initialize
+      @child_indicated_schemas_map = jsi_memomap(key_by: BY_TOKEN, &method(:jsi_child_indicated_schemas_compute))
+      @child_applied_schemas_map = jsi_memomap(key_by: BY_TOKEN, &method(:jsi_child_applied_schemas_compute))
     end
 
     def jsi_child_node_compute(token: , child_indicated_schemas: , child_applied_schemas: , includes: )
         jsi_class = JSI::SchemaClasses.class_for_schemas(child_applied_schemas,
           includes: includes,
+          mutable: jsi_mutable?,
         )
-        jsi_class.new(@jsi_document,
+        jsi_class.new(
+          jsi_document: @jsi_document,
           jsi_ptr: @jsi_ptr[token],
           jsi_indicated_schemas: child_indicated_schemas,
-          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 : jsi_schema_resource_ancestors,
-          jsi_schema_registry: jsi_schema_registry,
+          jsi_schema_dynamic_anchor_map: jsi_child_dynamic_anchor_map(token: token, child_schemas: child_applied_schemas),
           jsi_root_node: @jsi_root_node,
-        )
+        ).send(:jsi_initialized)
+    end
+
+    def jsi_child_dynamic_anchor_map(token: , child_schemas: )
+      metaschema = child_schemas.detect(&:describes_schema?)
+      # note: no memoized dialect.bootstrap_schema; this is only used once.
+      if metaschema && MetaSchemaNode::BootstrapSchema.new(dialect: metaschema.dialect, jsi_document: jsi_document, jsi_ptr: jsi_ptr[token], jsi_base_uri: jsi_next_base_uri).jsi_is_resource_root?
+        # if the child is a resource root, compute dynamic scope for it
+        # TODO if without_node removes the child, that probably means the child is equal to a descendent
+        # of another dynamic_root. not sure if this should find/return that child - one one hand
+        # instantiating multiple equal nodes via different dynamic scopes isn't ideal; on the other
+        # hand having child_node return a node with a different jsi_root_node may also be problematic.
+        jsi_next_schema_dynamic_anchor_map.without_node(self, ptr: jsi_ptr[token])
+      else
+        # child is not a resource, has the same dynamic scope as self
+        jsi_schema_dynamic_anchor_map
+      end
     end
 
     def jsi_child_indicated_schemas_compute(token: , content: )
-      jsi_schemas.child_applicator_schemas(token, content)
+      if jsi_schemas.any?(&:application_requires_evaluated)
+        # if application_requires_evaluated, in-place application needs to collect token evaluation
+        # recursively to inform child application, so must be recomputed.
+        jsi_indicated_schemas.each_yield_set do |is, y|
+          is.each_inplace_child_applicator_schema(token, content,
+            collect_evaluated_validate: jsi_conf.application_collect_evaluated_validate,
+            &y
+          )
+        end
+      else
+        # if token evaluation does not need to be collected, use our already-computed #jsi_schemas.
+        jsi_schemas.each_yield_set do |s, y|
+          s.each_child_applicator_schema(token, content, &y)
+        end
+      end
     end
 
     def jsi_child_applied_schemas_compute(token: , child_indicated_schemas: , child_content: )
-      child_indicated_schemas.inplace_applicator_schemas(child_content)
+      child_indicated_schemas.each_yield_set do |cis, y|
+        cis.each_inplace_applicator_schema(child_content, &y)
+      end
     end
 
-    def jsi_child_as_jsi(child_content, child_schemas, as_jsi)
+    def jsi_child_as_jsi(child_node, as_jsi)
       if [true, false].include?(as_jsi)
         child_as_jsi = as_jsi
       elsif as_jsi == :auto
-        child_is_complex = child_content.respond_to?(:to_hash) || child_content.respond_to?(:to_ary)
-        child_is_schema = child_schemas.any?(&:describes_schema?)
-        child_as_jsi = child_is_complex || child_is_schema
+        child_as_jsi = child_node.jsi_as_child_default_as_jsi
       else
         raise(ArgumentError, "as_jsi must be one of: :auto, true, false")
       end
 
       if child_as_jsi
-        yield
+        child_node
       else
-        child_content
+        child_node.jsi_node_content
       end
     end
 
@@ -734,5 +1140,16 @@ module JSI
         "instance: #{jsi_instance.pretty_inspect.chomp}",
       ].join("\n"))
     end
+
+    # Note that #initialize does not invoke the jsi_conf.after_initialize callback, because
+    # the node is not finished initializing when #initialize returns; other included modules
+    # or subclasses with #initialize methods calling super still need to finish.
+    # Places where Base is directly instantiated must call #jsi_initialized.
+    # @return [self]
+    def jsi_initialized
+      #chkbug fail if defined?(super) # this should be the last jsi_initialized in class ancestry
+      jsi_conf.after_initialize.call(self) if jsi_conf.after_initialize
+      self
+    end
   end
 end