openehr 1.2.999999 → 2.0.0

data/lib/openehr/am/template.rb

@@ -1,49 +1,102 @@
+require_relative 'archetype'
+
 module OpenEHR
   module AM
     module Template
-      class OperationalTemplate
-        attr_reader :uid, :concept, :language, :description, :template_id, :definition, :component_terminologies
+      # OPERATIONAL_TEMPLATE class represents a "compiled" template derived from 
+      # a source TEMPLATE by a "flattening" process, used for generating and 
+      # validating reference model instance data.
+      # According to openEHR AOM2 specification, it inherits from AUTHORED_ARCHETYPE.
+      class OperationalTemplate < OpenEHR::AM::Archetype::Archetype
+        attr_reader :component_terminologies, :terminology_extracts, :template_id
 
         def initialize(args = {})
-          self.uid = args[:uid]
-          self.concept = args[:concept]
+          # template_id must be validated before delegating to Archetype#initialize:
+          # OPERATIONAL_TEMPLATE identifies itself by template_id, and archetype_id
+          # is derived from it below, so an absent template_id must fail with a
+          # template-specific message rather than falling through to Archetype's
+          # own (unrelated) mandatory-field checks.
           self.template_id = args[:template_id]
-          self.language = args[:language]
-          self.description = args[:description]
-          self.definition = args[:definition]
-          self.component_terminologies = args[:component_terminologies]
+
+          # Initialize parent archetype with template-specific archetype_id
+          template_args = args.dup
+          template_args[:archetype_id] = args[:template_id] if args[:template_id] && !args[:archetype_id]
+
+          super(template_args)
+
+          self.component_terminologies = args[:component_terminologies] || {}
+          self.terminology_extracts = args[:terminology_extracts] || {}
         end
 
-        def uid=(uid)
-          @uid = uid
+        def template_id=(template_id)
+          if template_id.nil?
+            raise ArgumentError, 'template_id is mandatory for operational template'
+          end
+          @template_id = template_id
+          # Update archetype_id to match template_id for consistency
+          @archetype_id = template_id if template_id
         end
 
+        # An operational template's concept is commonly derived from its
+        # archetype_id (see #concept below) rather than supplied explicitly,
+        # so unlike Archetype#concept= it must not require a value up front.
         def concept=(concept)
-          raise ArgumentError if concept.nil?
           @concept = concept
         end
 
-        def language=(language)
-          @language = language
+        # AuthoredResource#description has no mandatory check, but an
+        # operational template always carries its own resource description.
+        def description=(description)
+          if description.nil?
+            raise ArgumentError, 'description is mandatory'
+          end
+          @description = description
         end
 
-        def template_id=(template_id)
-          raise ArgumentError if template_id.nil?
-          @template_id = template_id
+        def component_terminologies=(component_terminologies)
+          @component_terminologies = component_terminologies || {}
         end
 
-        def description=(description)
-          raise ArgumentError if description.nil?
-          @description=description 
+        def terminology_extracts=(terminology_extracts)
+          @terminology_extracts = terminology_extracts || {}
         end
 
-        def definition=(definition)
-          raise ArgumentError if definition.nil?
-          @definition = definition
+        # Returns true if this is a valid operational template
+        def is_valid_operational_template?
+          return false if template_id.nil?
+          return false if definition.nil?
+          return false if component_terminologies.nil?
+          true
         end
 
-        def component_terminologies=(component_terminologies)
-          @component_terminologies = component_terminologies
+        # Returns whether the template is specialized (should be true for operational templates)
+        def is_specialized?
+          !parent_archetype_id.nil?
+        end
+
+        # Get all archetype identifiers referenced in this operational template
+        def referenced_archetype_ids
+          component_terminologies.keys
+        end
+
+        # Get terminology for a specific archetype
+        def terminology_for_archetype(archetype_id)
+          component_terminologies[archetype_id]
+        end
+
+        # Override concept to use template concept or fallback to archetype concept
+        def concept
+          @concept || (archetype_id ? archetype_id.concept_name : nil)
+        end
+
+        # Compatibility method for backward compatibility with existing tests
+        def language
+          original_language
+        end
+
+        # Compatibility setter for language (maps to original_language)
+        def language=(language)
+          self.original_language = language
         end
       end
     end

data/lib/openehr/aql/engine/binding.rb

@@ -0,0 +1,13 @@
+module OpenEHR
+  module AQL
+    # A single row-candidate produced while walking the FROM clause's
+    # containment tree: the Dataset::EHRRecord it came from (for "e/..."
+    # root paths) plus the RM objects bound to each FROM variable so far
+    # (e.g. {"c" => a_composition, "o" => an_observation}).
+    Binding = Struct.new(:ehr_record, :variables, keyword_init: true) do
+      def [](name)
+        variables.fetch(name) { raise SemanticError, "unbound variable: #{name.inspect}" }
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/contains_resolver.rb

@@ -0,0 +1,161 @@
+require_relative 'binding'
+
+module OpenEHR
+  module AQL
+    # Walks a FromClause's containment tree against a Dataset, producing
+    # one Binding per match.
+    #
+    # An EHR root variable (bound to the Dataset::EHRRecord itself - not
+    # an OpenEHR::RM::EHR::EHR - since a Dataset element doesn't have to
+    # carry one; see Dataset's own header comment), a right-recursive
+    # CONTAINS chain searching a matched Locatable's *entire* subtree
+    # (any depth, via Pathable#path_children) for the next class,
+    # archetype-predicate filtering, AND/OR-grouped sibling branches
+    # (cross-product / union of each branch's matches) and NOT CONTAINS
+    # (parent matches survive only when the negated class is absent).
+    # standardPredicate/nodePredicate filtering and an EHR-level
+    # predicate (e.g. "[ehr_id/value=$ehr_id]") are added by a later
+    # engine milestone.
+    class ContainsResolver
+      def initialize(from_clause, dataset)
+        @root = from_clause.containment
+        @dataset = dataset
+      end
+
+      def each_binding
+        return enum_for(:each_binding) unless block_given?
+
+        @dataset.each_ehr do |ehr_record|
+          resolve(@root, ehr_record, ehr_record.compositions).each do |variables, _bound|
+            yield Binding.new(ehr_record: ehr_record, variables: variables)
+          end
+        end
+      end
+
+      private
+
+      # Returns an Array of [variables_hash, bound_object] pairs. `pool`
+      # is the Enumerable of Pathable candidates in scope for this node:
+      # an EHR record's top-level compositions at the root, or a parent
+      # match's full recursive descendant set below a CONTAINS.
+      # `bound_object` lets the caller (a further CONTAINS) compute the
+      # next-level pool from wherever this node ended up.
+      def resolve(node, ehr_record, pool)
+        case node
+        when Model::ClassExpression
+          resolve_class_expression(node, ehr_record, pool)
+        when Model::Containment
+          resolve_containment(node, ehr_record, pool)
+        when Model::ContainmentAnd
+          resolve_containment_and(node, ehr_record, pool)
+        when Model::ContainmentOr
+          resolve_containment_or(node, ehr_record, pool)
+        else
+          raise ExecutionError, "cannot execute a #{node.class} containment yet"
+        end
+      end
+
+      def resolve_class_expression(class_expression, ehr_record, pool)
+        return [[variables_for(class_expression, ehr_record), ehr_record]] if ehr_root?(class_expression)
+
+        pool.select { |candidate| matches?(candidate, class_expression) }
+            .map { |candidate| [variables_for(class_expression, candidate), candidate] }
+      end
+
+      def resolve_containment(containment, ehr_record, pool)
+        parent_matches = resolve(containment.parent, ehr_record, pool)
+        return negated_matches(containment, ehr_record, parent_matches) if containment.negated
+
+        parent_matches.flat_map do |parent_vars, parent_obj|
+          resolve(containment.child, ehr_record, descendant_pool(parent_obj, ehr_record)).map do |child_vars, child_obj|
+            [parent_vars.merge(child_vars), child_obj]
+          end
+        end
+      end
+
+      # "A NOT CONTAINS B": a parent match survives only when B has no
+      # match anywhere in that parent's subtree. B never binds a
+      # variable (there's nothing to bind an absence to).
+      def negated_matches(containment, ehr_record, parent_matches)
+        parent_matches.select do |_parent_vars, parent_obj|
+          resolve(containment.child, ehr_record, descendant_pool(parent_obj, ehr_record)).empty?
+        end
+      end
+
+      # "A CONTAINS (B AND C)": both branches must match somewhere in
+      # the same pool; every combination of a B-match and a C-match
+      # becomes its own binding (AQL has no correlation between sibling
+      # branches beyond sharing a parent).
+      def resolve_containment_and(node, ehr_record, pool)
+        left_matches = resolve(node.left, ehr_record, pool)
+        return [] if left_matches.empty?
+
+        right_matches = resolve(node.right, ehr_record, pool)
+        return [] if right_matches.empty?
+
+        left_matches.flat_map do |left_vars, _left_obj|
+          right_matches.map { |right_vars, right_obj| [left_vars.merge(right_vars), right_obj] }
+        end
+      end
+
+      # "A CONTAINS (B OR C)": either branch matching is enough; each
+      # branch's matches contribute their own bindings independently.
+      def resolve_containment_or(node, ehr_record, pool)
+        resolve(node.left, ehr_record, pool) + resolve(node.right, ehr_record, pool)
+      end
+
+      def descendant_pool(bound_object, ehr_record)
+        return ehr_record.compositions if bound_object.equal?(ehr_record)
+
+        descendants_of(bound_object)
+      end
+
+      # A subtree walk (any depth) over Pathable#path_children, matching
+      # real AQL CONTAINS semantics ("anywhere below", not just direct
+      # children).
+      def descendants_of(root)
+        results = []
+        queue = child_values(root)
+        until queue.empty?
+          node = queue.shift
+          next unless node.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+          results << node
+          queue.concat(child_values(node))
+        end
+        results
+      end
+
+      def child_values(node)
+        node.path_children.values.flat_map { |value| value.is_a?(Array) ? value : [value] }
+      end
+
+      def matches?(candidate, class_expression)
+        return false unless OpenEHR::RM.subtype_of?(candidate, class_expression.class_name)
+
+        predicate_matches?(candidate, class_expression.predicate)
+      end
+
+      def predicate_matches?(candidate, predicate)
+        case predicate
+        when nil
+          true
+        when Model::ArchetypePredicate
+          candidate.respond_to?(:archetype_node_id) && candidate.archetype_node_id == predicate.archetype_id
+        else
+          raise ExecutionError, "cannot evaluate a #{predicate.class} predicate yet"
+        end
+      end
+
+      def variables_for(class_expression, matched)
+        return {} unless class_expression.variable
+
+        { class_expression.variable => matched }
+      end
+
+      def ehr_root?(class_expression)
+        class_expression.class_name.upcase == 'EHR'
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/dataset.rb

@@ -0,0 +1,122 @@
+require_relative '../errors'
+
+# OpenEHR::AQL::Dataset is the AQL engine's only input boundary, and the
+# whole of its framework/ORM independence: everything under
+# lib/openehr/aql/ talks to "wherever your data lives" exclusively
+# through this class, which itself talks to nothing but the Ruby
+# `Enumerable`/`#each` protocol and this gem's own RM classes. No
+# ActiveRecord/Rails/Sequel/etc. is required or referenced anywhere
+# here or downstream - see the project plan's "Dataset:
+# フレームワーク/ORM非依存の契約" section for the full design rationale.
+#
+# Construction is cheap and never iterates its source (laziness is
+# preserved end to end); each element is normalized into an EHRRecord
+# only as #each_ehr actually walks it.
+#
+#   Dataset.new(ehrs:)                       # ehrs: anything #each-able
+#   Dataset.of_compositions(compositions, ehr_id: nil)
+#   Dataset.wrap(source)                     # Dataset / Composition-Enumerable / EHR-shaped-Enumerable
+#
+# Each element of `ehrs:` must be one of:
+#   - a Hash (symbol or string keys): {ehr_id:, compositions:, ehr_status: (optional)}
+#   - a duck-typed object responding to #ehr_id / #compositions (/ #ehr_status)
+#   - a full OpenEHR::RM::EHR::EHR (unwrapped via ehr_id.value,
+#     compositions.map { |vc| vc.latest_version.data }, and
+#     ehr_status.latest_version.data)
+#
+# Every element yielded by a record's compositions MUST be
+# is_a?(OpenEHR::RM::Common::Archetyped::Pathable) - anything else
+# raises DatasetError immediately, naming the offending class and
+# index. This is the deliberate anti-leak mechanism that keeps loose
+# ActiveRecord rows (or any other non-RM object) from half-working via
+# accidental duck typing.
+module OpenEHR
+  module AQL
+    class Dataset
+      EHRRecord = Struct.new(:ehr_id, :ehr, :ehr_status, :compositions, keyword_init: true)
+
+      def self.of_compositions(compositions, ehr_id: nil)
+        new(ehrs: [{ ehr_id: ehr_id, compositions: compositions }])
+      end
+
+      def self.wrap(source)
+        return source if source.is_a?(Dataset)
+
+        unless source.is_a?(Enumerable)
+          raise DatasetError, "cannot build a Dataset from a #{source.class} (expected a Dataset or an Enumerable)"
+        end
+
+        first, rest = source.first, source
+        return of_compositions(rest) if first.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+        new(ehrs: rest)
+      end
+
+      def initialize(ehrs:)
+        @ehrs = ehrs
+      end
+
+      def each_ehr
+        return enum_for(:each_ehr) unless block_given?
+
+        @ehrs.each { |element| yield normalize(element) }
+      end
+
+      private
+
+      def normalize(element)
+        return from_ehr(element) if element.is_a?(OpenEHR::RM::EHR::EHR)
+        return from_hash(element) if element.is_a?(Hash)
+
+        from_record(element)
+      end
+
+      def from_hash(hash)
+        stringified = hash.transform_keys(&:to_s)
+        build_record(
+          ehr_id: stringified['ehr_id'],
+          ehr: nil,
+          ehr_status: stringified['ehr_status'],
+          compositions: stringified['compositions']
+        )
+      end
+
+      def from_record(record)
+        build_record(
+          ehr_id: record.ehr_id,
+          ehr: nil,
+          ehr_status: record.respond_to?(:ehr_status) ? record.ehr_status : nil,
+          compositions: record.compositions
+        )
+      end
+
+      def from_ehr(ehr)
+        build_record(
+          ehr_id: ehr.ehr_id,
+          ehr: ehr,
+          ehr_status: ehr.ehr_status&.latest_version&.data,
+          compositions: ehr.compositions.map { |versioned_composition| versioned_composition.latest_version.data }
+        )
+      end
+
+      def build_record(ehr_id:, ehr:, ehr_status:, compositions:)
+        compositions = Array(compositions)
+        compositions.each_with_index do |composition, index|
+          next if composition.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+          raise DatasetError,
+                "Dataset compositions must be OpenEHR::RM RM objects (Pathable), " \
+                "got #{composition.class} at index #{index}"
+        end
+
+        EHRRecord.new(ehr_id: unwrap_id(ehr_id), ehr: ehr, ehr_status: ehr_status, compositions: compositions)
+      end
+
+      def unwrap_id(id)
+        return nil if id.nil?
+
+        id.respond_to?(:value) ? id.value : id
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/path_evaluator.rb

@@ -0,0 +1,137 @@
+module OpenEHR
+  module AQL
+    # Evaluates a columnExpr/terminal Model node against a Binding.
+    #
+    # SELECT paths ("o/data[at0001]/.../value/magnitude", "c/name/value")
+    # walk one segment at a time: as long as the current value is
+    # Pathable AND the segment names one of its *declared*
+    # `path_attribute`s (the content-structure attributes PATHABLE
+    # navigation was built for - see lib/openehr/rm/common/archetyped.rb),
+    # the hop goes through PATHABLE#items_at_path (reusing its predicate
+    # matching for node/archetype predicates). Everything else - RM
+    # metadata that isn't part of that DSL (name, archetype_details,
+    # composer, ...) and genuinely non-Pathable values (a DV_QUANTITY's
+    # magnitude, a DV_TEXT's value) - is a plain attribute read via a
+    # whitelisted public_send, never an arbitrary send driven by query
+    # text. A predicate directly on an identifiedPath's own variable
+    # (e.g. "c[at001]/..."), parameters and function calls are added by
+    # later engine milestones.
+    module PathEvaluator
+      # Attribute hops not reachable through the path_attribute DSL.
+      # Expand only when a real query needs another one - see the
+      # project's "no arbitrary send" rule in the class comment above.
+      ALLOWED_TERMINAL_HOPS = %w[magnitude name value].freeze
+
+      # Dataset::EHRRecord#ehr_id is already an unwrapped String (see
+      # Dataset's own header comment), but AQL's "e/ehr_id/value" syntax
+      # still expects a HierObjectID-shaped hop with its own #value -
+      # this tiny wrapper bridges that gap.
+      EhrIdValue = Struct.new(:value)
+
+      module_function
+
+      def evaluate(expression, binding)
+        case expression
+        when Model::IdentifiedPath
+          evaluate_identified_path(expression, binding)
+        when Model::Literal
+          expression.value
+        else
+          raise ExecutionError, "cannot evaluate a #{expression.class} yet"
+        end
+      end
+
+      def evaluate_identified_path(path, binding)
+        raise ExecutionError, 'predicates on a SELECT variable are not yet supported' if path.predicate
+
+        value = binding[path.variable]
+        return value unless path.path
+
+        path.path.segments.reduce(value) do |current, segment|
+          current.nil? ? nil : navigate(current, segment)
+        end
+      end
+
+      def navigate(current, segment)
+        return navigate_ehr_record(current, segment) if current.is_a?(Dataset::EHRRecord)
+
+        if declared_path_attribute?(current, segment)
+          navigate_pathable(current, segment)
+        else
+          navigate_terminal(current, segment)
+        end
+      end
+
+      # "e/ehr_id/value" and "e/ehr_status/..." always resolve (from
+      # Dataset's own record shape); any other "e/..." path falls
+      # through to whatever full RM::EHR::EHR the record carries, if
+      # any, else resolves to nil rather than erroring - AQL's
+      # path-absent-means-null semantics again, not a missing feature.
+      def navigate_ehr_record(record, segment)
+        raise ExecutionError, "path predicates on an EHR root are not supported (#{segment.attribute})" if segment.predicate
+
+        case segment.attribute
+        when 'ehr_id' then EhrIdValue.new(record.ehr_id)
+        when 'ehr_status' then record.ehr_status
+        else
+          record.ehr.nil? ? nil : navigate(record.ehr, segment)
+        end
+      end
+
+      def declared_path_attribute?(current, segment)
+        current.is_a?(OpenEHR::RM::Common::Archetyped::Pathable) &&
+          current.class.path_attributes.map(&:to_s).include?(segment.attribute)
+      end
+
+      # A path segment matching nothing is a legitimate "no value here"
+      # (AQL's path-absent-means-null semantics, same convention as
+      # PATHABLE#item_at_path itself), not an error - only an
+      # *ambiguous* match (more than one item) is.
+      def navigate_pathable(current, segment)
+        matches = current.items_at_path(rm_path_for(segment))
+        case matches.size
+        when 0 then nil
+        when 1 then matches.first
+        else raise ExecutionError, "path segment #{segment.to_s.inspect} matched #{matches.size} items " \
+                                    '(fan-out SELECT paths are not yet supported)'
+        end
+      end
+
+      def navigate_terminal(current, segment)
+        raise ExecutionError, "path predicates on a non-Pathable value are not supported (#{segment.attribute})" if segment.predicate
+        unless ALLOWED_TERMINAL_HOPS.include?(segment.attribute)
+          raise ExecutionError, "unsupported path attribute #{segment.attribute.inspect} on a #{current.class}"
+        end
+
+        current.public_send(segment.attribute)
+      end
+
+      def rm_path_for(segment)
+        return "/#{segment.attribute}" unless segment.predicate
+
+        "/#{segment.attribute}[#{predicate_path_text(segment.predicate)}]"
+      end
+
+      def predicate_path_text(predicate)
+        case predicate
+        when Model::ArchetypePredicate
+          predicate.archetype_id
+        when Model::NodePredicate
+          node_predicate_path_text(predicate)
+        else
+          raise ExecutionError, "cannot evaluate a #{predicate.class} path predicate yet"
+        end
+      end
+
+      def node_predicate_path_text(predicate)
+        return predicate.code unless predicate.value
+
+        unless predicate.value.is_a?(String)
+          raise ExecutionError, "cannot evaluate a #{predicate.value.class} node predicate value yet"
+        end
+
+        "#{predicate.code}, '#{predicate.value}'"
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/predicate_evaluator.rb

@@ -0,0 +1,65 @@
+module OpenEHR
+  module AQL
+    # Evaluates a WHERE clause's boolean expression tree against a
+    # Binding and the query's runtime params. E5 scope: comparisons
+    # (reusing PathEvaluator for both sides), AND/OR/NOT and EXISTS.
+    # LIKE, MATCHES and functionCall operands are added by later engine
+    # milestones.
+    module PredicateEvaluator
+      COMPARATORS = {
+        '=' => :==, '!=' => :!=, '<' => :<, '<=' => :<=, '>' => :>, '>=' => :>=
+      }.freeze
+
+      module_function
+
+      # `expression` is nil when there is no WHERE clause at all.
+      def matches?(expression, binding, params)
+        case expression
+        when nil
+          true
+        when Model::Comparison
+          evaluate_comparison(expression, binding, params)
+        when Model::AndExpr
+          matches?(expression.left, binding, params) && matches?(expression.right, binding, params)
+        when Model::OrExpr
+          matches?(expression.left, binding, params) || matches?(expression.right, binding, params)
+        when Model::NotExpr
+          !matches?(expression.operand, binding, params)
+        when Model::ExistsExpr
+          !PathEvaluator.evaluate(expression.path, binding).nil?
+        else
+          raise ExecutionError, "cannot evaluate a #{expression.class} WHERE expression yet"
+        end
+      end
+
+      # A comparison against an absent (nil) value is neither true nor
+      # false in AQL/SQL terms - it simply fails to select the row, the
+      # same as SQL's NULL-comparison-is-UNKNOWN convention.
+      def evaluate_comparison(comparison, binding, params)
+        left = resolve_operand(comparison.left, binding, params)
+        right = resolve_operand(comparison.right, binding, params)
+        return false if left.nil? || right.nil?
+
+        compare(left, comparison.operator, right)
+      end
+
+      def resolve_operand(node, binding, params)
+        return lookup_param(node, params) if node.is_a?(Model::Parameter)
+
+        PathEvaluator.evaluate(node, binding)
+      end
+
+      def lookup_param(parameter, params)
+        return params[parameter.name.to_sym] if params.key?(parameter.name.to_sym)
+        return params[parameter.name] if params.key?(parameter.name)
+
+        raise UnboundParameterError, "unbound parameter: $#{parameter.name}"
+      end
+
+      def compare(left, operator, right)
+        method = COMPARATORS.fetch(operator) { raise ExecutionError, "unknown comparison operator #{operator.inspect}" }
+        left.public_send(method, right)
+      end
+    end
+  end
+end