mxrb 0.1.0

data/lib/mxrb/model/page.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+require_relative "unit"
+
+module Mxrb
+  module Model
+    # $Type: Pages$Page / Forms$Page
+    # ContainmentName: "Documents"
+    class Page < Unit
+      attr_reader :name, :documentation, :url, :layout_id, :title,
+                  :popup_width, :popup_height, :popup_resizable, :excluded,
+                  :allowed_module_roles, :parameters, :export_level,
+                  :widgets, :data_source, :raw_document
+
+      def decode(doc)
+        @raw_document        = doc
+        @storage_type        = doc["$Type"] || "Forms$Page"
+        @name                = doc["Name"] || doc["name"]
+        @documentation       = doc["Documentation"] || doc["documentation"] || ""
+        @url                 = doc["Url"] || doc["URL"] || doc["url"] || ""
+        @title               = extract_text(doc["Title"] || doc["title"])
+        @layout_id           = extract_layout(doc)
+        @popup_width         = doc["PopupWidth"] || 0
+        @popup_height        = doc["PopupHeight"] || 0
+        @popup_resizable     = doc["PopupResizable"] == true
+        @excluded            = doc["Excluded"] == true
+        @export_level        = doc["ExportLevel"] || "Hidden"
+        @allowed_module_roles = parse_array(doc["AllowedModuleRoles"] || doc["AllowedRoles"] || doc["allowedModuleRoles"])
+        @parameters          = parse_array(doc["Parameters"] || doc["parameters"])
+        @widgets             = []
+        parse_widgets(widget_roots(doc))
+      end
+
+      def to_bson
+        {
+          "$ID"                => @id,
+          "$Type"              => @storage_type,
+          "Name"               => @name,
+          "Documentation"      => @documentation || "",
+          "Url"                => @url || "",
+          "Title"              => serialize_title,
+          "Layout"             => @layout_id,
+          "MarkAsUsed"         => false,
+          "Excluded"           => @excluded || false,
+          "AllowedModuleRoles" => IO::BsonCodec.build_array(@allowed_module_roles || [], marker: 1),
+          "Parameters"         => IO::BsonCodec.build_array(@parameters || []),
+          "PopupWidth"         => @popup_width || 0,
+          "PopupHeight"        => @popup_height || 0,
+          "PopupResizable"     => @popup_resizable || false,
+          "ExportLevel"        => @export_level || "Hidden",
+        }
+      end
+
+      def inspect
+        "#<Mxrb::Page name=#{@name.inspect} layout=#{@layout_id.to_s.slice(0, 8)}>"
+      end
+
+      private
+
+      def extract_text(obj)
+        return obj if obj.is_a?(String)
+        return "" unless obj.is_a?(Hash)
+        return extract_text(obj["Template"]) if obj["$Type"] == "Forms$ClientTemplate"
+
+        translations = parse_array(obj["Translations"] || obj["Items"] || obj["translations"] || [])
+        translation = translations.first
+        return "" unless translation.is_a?(Hash)
+
+        translation["Translation"] || translation["Text"] || translation["text"] || ""
+      end
+
+      def extract_layout(doc)
+        return doc.dig("FormCall", "Form") if doc.dig("FormCall", "Form")
+
+        IO::BsonCodec.extract_id(doc["Layout"] || doc["LayoutId"])
+      end
+
+      def serialize_title
+        { "$ID" => SecureRandom.uuid, "$Type" => "Texts$Text", "Translations" => [1] }
+      end
+
+      def parse_widgets(items, target = @widgets)
+        items.each do |widget|
+          next unless widget.is_a?(Hash)
+          type = widget["$Type"]
+          if %w[Pages$DataView Forms$DataView].include?(type)
+            @data_source = parse_source(widget["DataSource"])
+            parse_widgets(child_widgets(widget), target)
+            next
+          end
+          if type == "CustomWidgets$CustomWidget"
+            target << pluggable_widget(widget)
+            next
+          end
+          if %w[Pages$DataGrid Forms$DataGrid].include?(type)
+            target << data_grid_widget(widget)
+            next
+          end
+          if %w[Pages$TabControl Forms$TabControl].include?(type)
+            target << tab_control_widget(widget)
+            next
+          end
+          if %w[Pages$SnippetCall Forms$SnippetCall Forms$SnippetCallWidget].include?(type)
+            snippet_ref = (
+              widget.dig("SnippetSettings", "Snippet") || widget.dig("FormCall", "Form")
+            ).to_s
+            target << { type: :snippet, name: widget["Name"] || "snippet",
+                        options: { snippet: snippet_ref }, events: [] }
+            next
+          end
+          if %w[Pages$Container Forms$Container Forms$DivContainer].include?(type)
+            children = []
+            parse_widgets(parse_array(widget["Widgets"]), children)
+            target << { type: :container, name: widget["Name"] || "container",
+                        options: container_options(widget), children: children, events: [] }
+            next
+          end
+          if layout_container?(widget)
+            parse_widgets(child_widgets(widget), target)
+            parse_form_call_arguments(widget["Arguments"], target)
+            next
+          end
+          unless supported_widget?(type)
+            target << native_widget(widget)
+            next
+          end
+
+          events = {
+            "OnChangeAction" => :on_change,
+            "OnEnterAction" => :on_enter,
+            "OnLeaveAction" => :on_leave,
+            "Action" => :on_click
+          }.filter_map do |property, event|
+            action = parse_action(widget[property])
+            action&.merge(event: event)
+          end
+          widget_type = widget_type(type)
+          target << {
+            type: widget_type,
+            name: widget["Name"],
+            options: widget_options(widget, widget_type),
+            events: events
+          }
+        end
+      end
+
+      def supported_widget?(type)
+        widget_type(type)
+      end
+
+      def widget_type(type)
+        case type
+        when "Pages$ActionButton", "Forms$ActionButton", "Forms$GridActionButton"
+          :button
+        when "Pages$TextBox", "Forms$TextBox"
+          :text_box
+        when "Pages$TextArea", "Forms$TextArea"
+          :text_area
+        when "Pages$CheckBox", "Forms$CheckBox"
+          :check_box
+        when "Pages$DatePicker", "Forms$DatePicker"
+          :date_picker
+        when "Pages$ReferenceSelector", "Forms$ReferenceSelector",
+             "Pages$InputReferenceSetSelector", "Forms$InputReferenceSetSelector"
+          :reference_selector
+        when "Pages$DynamicText", "Forms$DynamicText", "Pages$Label", "Forms$Label"
+          :text
+        when "Pages$DropDownWidget", "Forms$DropDownWidget", "Forms$DropDown"
+          :drop_down
+        end
+      end
+
+      def widget_options(widget, widget_type)
+        options = {
+          attribute: attribute_path(widget),
+          caption: widget_caption(widget, widget_type)
+        }.compact
+        options[:lines] = widget["NumberOfLines"] if widget_type == :text_area && widget["NumberOfLines"]
+        options
+      end
+
+      def container_options(widget)
+        class_name = widget.dig("Appearance", "Class") || widget["Class"]
+        class_name.to_s.empty? ? {} : { class: class_name }
+      end
+
+      def attribute_path(widget)
+        widget["AttributePath"] || widget.dig("AttributeRef", "Attribute")
+      end
+
+      def widget_caption(widget, widget_type)
+        return extract_text(widget["Content"] || widget["Text"] || widget["LabelText"]) if widget_type == :text
+
+        extract_text(
+          widget["Caption"] ||
+          widget["LabelText"] ||
+          widget["LabelTemplate"] ||
+          widget.dig("CaptionTemplate", "Template")
+        )
+      end
+
+      def data_grid_widget(widget)
+        columns = parse_array(widget["Columns"]).map do |column|
+          {
+            name: column["Name"],
+            attribute: attribute_path(column),
+            caption: extract_text(column["Caption"])
+          }.compact
+        end
+        options = { entity: grid_entity(widget), columns: columns }.compact
+        options[:search_bar] = parse_search_bar(widget["SearchBar"]) if widget["SearchBar"].is_a?(Hash)
+        options[:toolbar]    = parse_toolbar(widget["ToolBar"])       if widget["ToolBar"].is_a?(Hash)
+        { type: :data_grid, name: widget["Name"], options: options, events: [] }
+      end
+
+      def pluggable_widget(widget)
+        case widget.dig("Type", "WidgetId")
+        when "com.mendix.widget.web.datagrid.Datagrid" then data_grid2_widget(widget)
+        when "com.mendix.widget.web.combobox.Combobox"  then combo_box_widget(widget)
+        else native_widget(widget)
+        end
+      end
+
+      def native_widget(widget)
+        deep = widget.reject { |key, _| %w[$ID $Type Name].include?(key.to_s) }
+        {
+          type: :native_widget, name: widget["Name"] || "widget",
+          options: { native_type: widget["$Type"], deep_structure: deep }, events: []
+        }
+      end
+
+      def data_grid2_widget(widget)
+        properties = custom_property_map(widget["Object"], widget.dig("Type", "ObjectType"))
+        entity = properties.dig("datasource", "DataSource", "EntityRef", "Entity")
+        column_type = custom_property_type(widget.dig("Type", "ObjectType"), "columns")
+                      &.dig("ValueType", "ObjectType")
+        columns = parse_array(properties.dig("columns", "Objects")).map do |object|
+          values = custom_property_map(object, column_type)
+          {
+            name: extract_text(values.dig("header", "TextTemplate")),
+            attribute: values.dig("attribute", "AttributeRef", "Attribute"),
+            caption: extract_text(values.dig("header", "TextTemplate"))
+          }.compact
+        end
+        {
+          type: :data_grid, name: widget["Name"],
+          options: { entity: entity, columns: columns }.compact, events: []
+        }
+      end
+
+      def combo_box_widget(widget)
+        properties = custom_property_map(widget["Object"], widget.dig("Type", "ObjectType"))
+        association = parse_array(properties.dig("attributeAssociation", "EntityRef", "Steps"))
+                      .first&.fetch("Association", nil)
+        reference = properties.dig("optionsSourceType", "PrimitiveValue") == "association"
+        attribute = if reference
+          association
+        else
+          properties.dig("attributeEnumeration", "AttributeRef", "Attribute")
+        end
+        options = {
+          attribute: attribute, caption: extract_text(widget["LabelTemplate"])
+        }.compact
+        if reference
+          options[:display_attribute] = properties.dig(
+            "optionsSourceAssociationCaptionAttribute", "AttributeRef", "Attribute"
+          )
+        end
+        { type: reference ? :reference_selector : :drop_down,
+          name: widget["Name"], options: options.compact, events: [] }
+      end
+
+      def custom_property_map(object, object_type)
+        return {} unless object.is_a?(Hash) && object_type.is_a?(Hash)
+
+        types = parse_array(object_type["PropertyTypes"]).to_h do |type|
+          [IO::BsonCodec.extract_id(type["$ID"]), type["PropertyKey"]]
+        end
+        parse_array(object["Properties"]).to_h do |property|
+          [types[IO::BsonCodec.extract_id(property["TypePointer"])], property["Value"]]
+        end.compact
+      end
+
+      def custom_property_type(object_type, key)
+        parse_array(object_type && object_type["PropertyTypes"]).find { _1["PropertyKey"] == key }
+      end
+
+      def parse_search_bar(sb)
+        return nil unless sb.is_a?(Hash)
+        fields = parse_array(sb["SearchFields"]).filter_map do |sf|
+          attr_ref = sf.dig("AttributeRef", "Attribute") || sf["Attribute"] || sf["AttributePath"]
+          next unless attr_ref
+          {
+            attribute: attr_ref.to_s.split("/").last,
+            caption: extract_text(sf["Label"] || sf["Caption"])
+          }
+        end
+        fields.empty? ? nil : { fields: fields }
+      end
+
+      def parse_toolbar(tb)
+        return nil unless tb.is_a?(Hash)
+        type_map = {
+          "Pages$GridNewButton"              => :new,
+          "Forms$GridNewButton"              => :new,
+          "Pages$GridDeleteButton"           => :delete,
+          "Forms$GridDeleteButton"           => :delete,
+          "Pages$GridSearchButton"           => :search,
+          "Forms$GridSearchButton"           => :search,
+          "Pages$GridExportToExcelButton"    => :export,
+          "Forms$GridExportToExcelButton"    => :export
+        }
+        buttons = parse_array(tb["Buttons"]).filter_map do |btn|
+          t = type_map[btn["$Type"]]
+          next unless t
+          { type: t, caption: extract_text(btn["Caption"]) }
+        end
+        buttons.empty? ? nil : { buttons: buttons }
+      end
+
+      def tab_control_widget(widget)
+        tabs = parse_array(widget["TabPages"]).map do |tab|
+          widgets = []
+          parse_widgets(parse_array(tab["Widgets"]), widgets)
+          {
+            name: tab["Name"],
+            caption: extract_text(tab["Caption"]),
+            widgets: widgets
+          }.compact
+        end
+        {
+          type: :tab_control,
+          name: widget["Name"],
+          options: { tabs: tabs },
+          events: []
+        }
+      end
+
+      def grid_entity(widget)
+        widget.dig("DataSource", "Entity") ||
+          widget.dig("DataSource", "EntityRef", "Entity")
+      end
+
+      def widget_roots(doc)
+        roots = parse_array(doc["Widgets"] || doc["widgets"])
+        roots.concat(form_call_widgets(doc["FormCall"]))
+        roots
+      end
+
+      def form_call_widgets(form_call)
+        return [] unless form_call.is_a?(Hash)
+
+        parse_array(form_call["Arguments"]).flat_map do |argument|
+          child_widgets(argument)
+        end
+      end
+
+      def parse_form_call_arguments(arguments, target = @widgets)
+        parse_array(arguments).each do |argument|
+          parse_widgets(child_widgets(argument), target)
+        end
+      end
+
+      def layout_container?(widget)
+        child_widgets(widget).any? || widget.key?("Arguments")
+      end
+
+      def child_widgets(widget)
+        direct = parse_array(widget["Widgets"]) + parse_array(widget["FooterWidgets"])
+        tab_widgets = parse_array(widget["TabPages"]).flat_map { parse_array(_1["Widgets"]) }
+        row_columns = parse_array(widget["Rows"]).flat_map { parse_array(_1["Columns"]) }
+        column_widgets = row_columns.flat_map { parse_array(_1["Widgets"]) }
+        direct + tab_widgets + column_widgets
+      end
+
+      def parse_source(source)
+        return nil unless source.is_a?(Hash)
+        result = if %w[Pages$NanoflowSource Forms$NanoflowSource].include?(source["$Type"])
+          { kind: :nanoflow, name: local_name(source["Nanoflow"] || source.dig("NanoflowSettings", "Nanoflow")) }
+        else
+          { kind: :microflow, name: local_name(source["Microflow"] || source.dig("MicroflowSettings", "Microflow")) }
+        end
+        result[:name].to_s.empty? ? nil : result
+      end
+
+      def parse_action(action)
+        return nil unless action.is_a?(Hash)
+        if %w[Pages$CallNanoflowClientAction Forms$CallNanoflowClientAction].include?(action["$Type"])
+          handler = local_name(action["Nanoflow"] || action.dig("NanoflowSettings", "Nanoflow"))
+          handler.to_s.empty? ? nil : { kind: :nanoflow, handler: handler }
+        elsif %w[Pages$MicroflowClientAction Forms$MicroflowAction Forms$MicroflowClientAction].include?(action["$Type"])
+          handler = local_name(action["Microflow"] || action.dig("MicroflowSettings", "Microflow"))
+          handler.to_s.empty? ? nil : { kind: :microflow, handler: handler }
+        elsif %w[Pages$SaveChangesClientAction Forms$SaveChangesClientAction].include?(action["$Type"])
+          { kind: :action, handler: "save_changes" }
+        elsif %w[Pages$CancelChangesClientAction Forms$CancelChangesClientAction].include?(action["$Type"])
+          { kind: :action, handler: "cancel_changes" }
+        elsif %w[Pages$DeleteClientAction Forms$DeleteClientAction].include?(action["$Type"])
+          { kind: :action, handler: "delete" }
+        elsif %w[Pages$ClosePageClientAction Forms$ClosePageClientAction].include?(action["$Type"])
+          { kind: :action, handler: "close_page" }
+        end
+      end
+
+      def local_name(name)
+        name.to_s.split(".").last
+      end
+    end
+  end
+end

data/lib/mxrb/model/project.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "../io/mpr_file"
+
+module Mxrb
+  module Model
+    class Project
+      attr_reader :mpr
+
+      def self.open(path, readonly: true)
+        new(IO::MprFile.open(path, readonly: readonly))
+      end
+
+      def initialize(mpr)
+        @mpr = mpr
+      end
+
+      def name            = @mpr.project_name
+      def mendix_version  = @mpr.mendix_version
+      def format_version  = @mpr.format_version
+
+      # ── Artefacts ──────────────────────────────────────────────────────
+
+      def modules
+        @modules ||= @mpr.units_by_containment("Modules").map { Module.new(_1, @mpr) }
+      end
+
+      def entities    = modules.flat_map(&:entities)
+      def pages       = modules.flat_map(&:pages)
+      def microflows  = modules.flat_map(&:microflows)
+
+      def navigation
+        @navigation ||= begin
+          raw = all_units.find { parse_bson(_1)["$Type"] == "Navigation$NavigationDocument" }
+          Navigation.new(raw && parse_bson(raw))
+        end
+      end
+
+      def design_system = (@design_system ||= DesignSystem.new(File.dirname(@mpr.path)))
+      def plan_design_token_migration(replacements) =
+        design_system.plan_literal_migration(replacements)
+
+      # ── Low-level exploration ───────────────────────────────────────────
+
+      def all_units   = @mpr.all_units
+      def tables      = @mpr.tables
+      def table_info(n) = @mpr.table_info(n)
+      def query(sql, *b) = @mpr.query(sql, *b)
+      def raw_unit(uuid) = @mpr.unit(uuid)
+      def children_of(uuid) = @mpr.children_of(uuid)
+      def parse_bson(raw)   = @mpr.parse_contents(raw)
+      def architecture_definition = @mpr.architecture_definition
+
+      # ── Native OQL inspection ───────────────────────────────────────────
+
+      def oql_queries = (@oql_catalog ||= Oql::Catalog.new(self)).queries
+      def oql? = !oql_queries.empty?
+      def oql_sql_views(dialect: :postgresql)
+        translator = Oql::Translator.new(dialect:)
+        oql_queries.map { translator.translate(_1) }.freeze
+      end
+      def oql_analysis(dialect: :postgresql)
+        analyzer = Oql::Analyzer.new(dialect:)
+        oql_queries.map { analyzer.analyze(_1) }.freeze
+      end
+
+      # ── Semantic analysis ───────────────────────────────────────────────
+
+      def semantic_index = (@semantic_index ||= Semantic::Index.new(self))
+      def semantic_cache_info
+        @mpr.index_cache_info(
+          current_fingerprint: Semantic::Index.fingerprint(self)
+        )
+      end
+      def warm_semantic_cache!
+        semantic_index
+        semantic_cache_info
+      end
+      def clear_semantic_cache!
+        removed = @mpr.clear_index_cache!
+        @semantic_index = nil
+        removed
+      end
+      def find_artifact(name, kind: nil) = semantic_index.find(name, kind: kind)
+      def search_artifacts(query, **filters) = semantic_index.search(query, **filters)
+      def semantic_search_artifacts(query, **options) =
+        semantic_index.semantic_search_artifacts(query, **options)
+      def semantic_search_hits(query, **options) =
+        semantic_index.semantic_search_hits(query, **options)
+      def describe_artifact(name) = semantic_index.describe(name)
+      def references_to(name) = semantic_index.references_to(name)
+      def references_from(name) = semantic_index.references_from(name)
+      def callers_of(name) = semantic_index.callers_of(name)
+      def callees_of(name) = semantic_index.callees_of(name)
+      def impact_of(name, transitive: true) =
+        semantic_index.impact_of(name, transitive: transitive)
+      def plan_rename(name, to:) = Semantic::Renamer.new(self).plan(name, to: to)
+      def rename!(name, to:) = plan_rename(name, to: to).apply!
+      def plan_remove(name) = Semantic::Remover.new(self).plan(name)
+      def remove!(name) = plan_remove(name).apply!
+      def plan_move(name, to:) = Semantic::Mover.new(self).plan(name, to: to)
+      def move!(name, to:) = plan_move(name, to: to).apply!
+      def plan_extract(name, as:, object_ids:) =
+        Semantic::Extractor.new(self).plan(name, as: as, object_ids: object_ids)
+      def extract!(name, as:, object_ids:) = plan_extract(name, as: as, object_ids: object_ids).apply!
+      def plan_inline(name, calling:) = Semantic::Inliner.new(self).plan(name, calling: calling)
+      def inline!(name, calling:) = plan_inline(name, calling: calling).apply!
+      def analyze(**options) = Semantic::Analyzer.new(self).analyze(**options)
+      alias lint analyze
+
+      # ── Domain model mutation ───────────────────────────────────────────────
+
+      def plan_add_attribute(entity, name:, type: :string, **opts) =
+        Semantic::DomainMutator.new(self).plan_add_attribute(entity, name: name, type: type, **opts)
+      def add_attribute!(entity, name:, type: :string, **opts) =
+        plan_add_attribute(entity, name: name, type: type, **opts).apply!
+
+      def plan_remove_attribute(attribute) =
+        Semantic::DomainMutator.new(self).plan_remove_attribute(attribute)
+      def remove_attribute!(attribute) = plan_remove_attribute(attribute).apply!
+
+      def plan_change_attribute(attribute, **updates) =
+        Semantic::DomainMutator.new(self).plan_change_attribute(attribute, **updates)
+      def change_attribute!(attribute, **updates) = plan_change_attribute(attribute, **updates).apply!
+
+      def plan_add_entity(mod, name:, **opts) =
+        Semantic::DomainMutator.new(self).plan_add_entity(mod, name: name, **opts)
+      def add_entity!(mod, name:, **opts) = plan_add_entity(mod, name: name, **opts).apply!
+
+      def plan_remove_entity(entity) =
+        Semantic::DomainMutator.new(self).plan_remove_entity(entity)
+      def remove_entity!(entity) = plan_remove_entity(entity).apply!
+
+      # ── Batch plan ──────────────────────────────────────────────────────────
+
+      def batch_plan(plans) = Semantic::BatchPlan.new(project: self, plans: Array(plans))
+      def evaluate(&block)
+        Evaluation::Suite.new(self).tap { _1.instance_eval(&block) }.run
+      end
+
+      # Structurally migrates the project to a different Mendix version.
+      # Requires an MXRB architecture definition stored in the MPR
+      # (i.e. the project was generated by MXRB). Re-runs the Writer with
+      # the target version so all version-specific BSON structures are
+      # regenerated correctly. Idempotent — safe to call multiple times.
+      def migrate_to!(version)
+        v = version.to_s
+        raise ArgumentError, "version must be a non-empty string" if v.empty?
+
+        definition = @mpr.architecture_definition
+        raise ArgumentError,
+              "no MXRB architecture definition found in this MPR — " \
+              "structural migration requires a project generated by MXRB" unless definition
+
+        path    = @mpr.path
+        readonly = @mpr.readonly?
+        raise ArgumentError, "project is opened read-only; reopen with readonly: false" if readonly
+
+        updated = definition.merge(version: v)
+        @mpr.close
+        Writer.new(path, updated).write!
+        @mpr = IO::MprFile.open(path, readonly: false)
+        @mpr.update_version!(v)
+        refresh!
+        self
+      end
+
+      alias upgrade_to!   migrate_to!
+      alias downgrade_to! migrate_to!
+
+      def refresh!
+        @modules = nil
+        @semantic_index = nil
+        @navigation = nil
+        @design_system = nil
+        @oql_catalog = nil
+        self
+      end
+
+      def close = @mpr.close
+
+      def inspect
+        "#<Mxrb::Project name=#{name.inspect} version=#{mendix_version.inspect} format=#{format_version}>"
+      end
+    end
+  end
+end

data/lib/mxrb/model/unit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../io/bson_codec"
+
+module Mxrb
+  module Model
+    # Base for all Mendix artefacts.
+    # Each subclass maps to a unit row whose Contents BSON has a specific $Type.
+    class Unit
+      attr_reader :id, :container_id, :containment_name, :mpr, :bson_type
+
+      def initialize(raw, mpr)
+        @id               = raw["UnitID"]
+        @container_id     = raw["ContainerID"]
+        @containment_name = raw["ContainmentName"]
+        @mpr              = mpr
+        doc               = mpr.parse_contents(raw)
+        @bson_type        = doc["$Type"] || doc["\$Type"]
+        decode(doc)
+      end
+
+      # Subclasses implement these
+      def decode(_doc); end
+      def to_bson;      raise NotImplementedError, "#{self.class}#to_bson not implemented"; end
+
+      def save!
+        doc = to_bson
+        if @id
+          @mpr.update_unit(@id, doc)
+        else
+          raise "Cannot insert without container_id" unless @container_id
+          @id = @mpr.insert_unit(
+            container_uuid:   @container_id,
+            containment_name: @containment_name,
+            contents_doc:     doc
+          )
+        end
+        self
+      end
+
+      protected
+
+      # Helpers for BSON field extraction
+      def extract_id(val) = IO::BsonCodec.extract_id(val)
+      def parse_array(arr) = IO::BsonCodec.parse_array(arr)[:items]
+    end
+  end
+end