metanorma-mko 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d552e397dd8ed669ba8766736e4fd97621ef7b3203598b162ff989c84691a59
+  data.tar.gz: 0d1babd1f3cfcecf0aa61055a4798bb91edcd7847c9936a624cbbcfe9dec45a1
+SHA512:
+  metadata.gz: bbe6e4797d6290ca828ed59c124d3b452d2b9a10f7ca59533e18c23be2f42316da55edbd14d2dbd88a8c9636659b6c15b7bde605c2cf1205a0f8a0909f9d034c
+  data.tar.gz: 6fa2e380044eecad731b5258b7c424651a815a3a0b6522ae47699d97e037ae121a49e770d8982bf5af89645ae5f2d0559f11a28d6ee31e5ed21074903406af07

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,44 @@
+= metanorma-mko
+
+Metanorma Knowledge Objects (MKO, MN 116) — the machine serialization
+format for Metanorma documents, as code.
+
+== What this gem owns
+
+The FORMAT contract:
+
+* the MN 116 wire schema (typed units, edges, document identity,
+  manifest) as lutaml-model classes — `Metanorma::Mko::Schema`;
+* the bundle layout and manifest verification — `Mko::Bundle`,
+  `Mko::Writer`;
+* hash-addressed assets (`Mko::Assets`);
+* structured edition diffs (`Mko::Diff`) and interlingual alignment
+  (`Mko::Alignment`);
+* the generated JSON Schemas — `Mko.json_schemas` (the schema classes
+  are the single source of truth; TS/Python consumers validate against
+  these, never hand-rolled copies);
+* the reference MCP server over any conforming bundle —
+  `Mko::Mcp::Server` (search_units / get_unit / walk_edges /
+  edition_diff; JSON-RPC 2.0 over stdio).
+
+== What it does not own
+
+The model side — the projection walk, collection orchestration, flavor
+resolution — lives in
+https://github.com/metanorma/metanorma-document[metanorma-document],
+which depends on this gem and reopens `Metanorma::Mko` with the export
+entry points (`Mko.export`, `Mko::Collection.export`).
+
+== Usage
+
+Consumers validate against the published contract:
+
+[source,ruby]
+require "metanorma/mko"
+Metanorma::Mko.json_schemas["unit"]
+# => { "$schema" => "https://json-schema.org/draft/2020-12/schema", ... }
+
+Agent consumers mount the reference MCP server:
+
+[source,ruby]
+Metanorma::Mko::Mcp::Server.new("oiml-r-60-1.mko").run

data/lib/metanorma/mko/alignment.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Metanorma
+  module Mko
+    # Interlingual alignment (MN 116 §stability, P2): units across
+    # language editions of the same document are the same knowledge
+    # object when their anchors match — Metanorma translations carry
+    # the semantic anchors. Emits variant_of unit edges binding the
+    # editions: parallel corpora, cross-language retrieval with
+    # source-language provenance, and consistency diffs between
+    # translations.
+    module Alignment
+      class << self
+        # Align two bundles of the same document (different language
+        # editions) by stable unit anchor. Returns [Schema::Edge] with
+        # kind variant_of; content-hash anchors (h-…) and unmatched
+        # units are simply not aligned — never guessed.
+        def align(bundle_a, bundle_b)
+          a = units_by_anchor(bundle_a)
+          b = units_by_anchor(bundle_b)
+          a.keys.intersection(b.keys).filter_map do |anchor|
+            next if anchor.to_s.empty? || anchor.start_with?("h-")
+
+            Schema::Edge.new(from: a[anchor], to: b[anchor],
+                              kind: "variant_of")
+          end
+        end
+
+        # Write alignment.jsonl into bundle_a's directory; returns the
+        # path. The alignment is a derived artifact — regeneration
+        # replaces it.
+        def export(bundle_a, bundle_b)
+          edges = align(bundle_a, bundle_b)
+          path = File.join(bundle_a, "alignment.jsonl")
+          File.write(path, edges.map(&:to_json).join("\n") + "\n")
+          path
+        end
+
+        private
+
+        def units_by_anchor(bundle)
+          file = File.join(bundle, "units.jsonl")
+          File.readlines(file).each_with_object({}) do |line, h|
+            unit = JSON.parse(line)
+            h[unit["anchor"]] = unit["id"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/assets.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+
+module Metanorma
+  module Mko
+    # Hash-addressed figure assets (MN 116 §assets). Bytes come from
+    # the model when it carries them (data URIs) and from the caller's
+    # source directory for relative paths — never from the walk's
+    # environment. Every asset lands in the bundle as assets/<sha256>,
+    # manifest-verified like every other component.
+    class Assets
+      Entry = Struct.new(:name, :media_type, :data, keyword_init: true)
+
+      DATA_URI = /\Adata:([^;,]+)(?:;charset=[^;,]+)?;base64,(.*)\z/m.freeze
+      MEDIA_TYPES = {
+        ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+        ".gif" => "image/gif", ".svg" => "image/svg+xml",
+        ".tif" => "image/tiff", ".tiff" => "image/tiff", ".webp" => "image/webp",
+      }.freeze
+
+      def initialize(source_dir: nil)
+        @source_dir = source_dir
+        @entries = {}
+      end
+
+      # Returns the asset reference ("assets/<sha256>") for a figure
+      # source, or nil when no bytes are available.
+      def attach(uri)
+        data, media_type = bytes_for(uri)
+        return nil unless data
+
+        sha = Digest::SHA256.hexdigest(data)
+        name = "assets/#{sha}"
+        @entries[name] ||= Entry.new(
+          name: name, media_type: media_type || media_type_for(uri), data: data
+        )
+        name
+      end
+
+      def entries
+        @entries.values
+      end
+
+      private
+
+      def bytes_for(uri)
+        text = uri.to_s
+        if (m = text.match(DATA_URI))
+          [Base64.decode64(m[2]), m[1]]
+        elsif @source_dir && !text.empty?
+          path = File.expand_path(text, @source_dir)
+          [File.binread(path), nil] if File.file?(path)
+        end
+      end
+
+      def media_type_for(uri)
+        MEDIA_TYPES[File.extname(uri.to_s).downcase] || "application/octet-stream"
+      end
+    end
+  end
+end

data/lib/metanorma/mko/bundle.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    # The on-disk bundle writer: one place that knows the file layout,
+    # the manifest bookkeeping, and the hash verification inputs. The
+    # projection Writer and the collection exporter both compose it —
+    # bundle mechanics are never duplicated.
+    class Bundle
+      attr_reader :dir
+
+      def self.open(short, to)
+        new(File.expand_path(File.join(to, "#{short}.mko")))
+      end
+
+      def initialize(dir)
+        @dir = dir
+        @manifest = Schema::Manifest.new(
+          schema: SCHEMA, schema_version: SCHEMA_VERSION,
+          generated: Schema::Generated.new(
+            tool: "metanorma-document", schema_version: SCHEMA_VERSION,
+          ),
+          components: []
+        )
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+      end
+
+      def add_json(name, file, object)
+        path = File.join(dir, file)
+        File.write(path, JSON.pretty_generate(JSON.parse(object.to_json)))
+        component(name: name, file: file, media_type: "application/json")
+      end
+
+      # Line-oriented component; the block serializes each item
+      # (framework to_json by default).
+      def add_lines(name, file, items, &serializer)
+        serializer ||= lambda(&:to_json)
+        path = File.join(dir, file)
+        File.write(path, "#{items.map(&serializer).join("\n")}\n")
+        component(name: name, file: file, media_type: "application/jsonl",
+                  count: items.size)
+      end
+
+      def add_asset(entry)
+        path = File.join(dir, entry.name)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, entry.data)
+        component(name: entry.name, file: entry.name,
+                  media_type: entry.media_type, count: 1)
+      end
+
+      def flavor=(flavor)
+        @manifest.generated.flavor = flavor
+      end
+
+      def source_file=(source)
+        @manifest.source_file = source
+      end
+
+      def write_manifest
+        @manifest.generated.timestamp = Time.now.utc.iso8601
+        File.write(File.join(dir, "manifest.json"),
+                   JSON.pretty_generate(JSON.parse(@manifest.to_json)))
+        dir
+      end
+
+      def zip!
+        require "zip"
+        zip_path = "#{dir}.zip"
+        Zip::File.open(zip_path, Zip::File::CREATE) do |zipfile|
+          Dir[File.join(dir, "**", "*")].each do |f|
+            next if File.directory?(f)
+
+            zipfile.add(f.sub("#{dir}/", ""), f)
+          end
+        end
+        zip_path
+      end
+
+      private
+
+      def component(name:, file:, media_type:, count: nil)
+        @manifest.components << Schema::ManifestComponent.new(
+          name: name, file: file, media_type: media_type,
+          count: count, hash: "sha256:#{Digest::SHA256.file(File.join(dir, file)).hexdigest}"
+        )
+      end
+    end
+  end
+end

data/lib/metanorma/mko/diff.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Metanorma
+  module Mko
+    # Structured edition diffs (MN 116 §diffs; issue #53 item 5):
+    # "what changed between the 2000 and the 2017 edition" becomes a
+    # machine answer, not an expert reading marathon. Built on the
+    # stable-id contract — units pair by anchor, content hashes say
+    # whether anything changed — so a diff is exact and incremental.
+    module Diff
+      class << self
+        # Two bundles of the same document (different editions).
+        # Returns a change set:
+        #   { from:, to:, added: [unit summaries], removed: [...],
+        #     changed: [{ anchor, type, number, fields: [...] }] }
+        # fields carries field-level detail (text, title, number, and
+        # typed payload fields: designations, definition, rows,
+        # statement, …).
+        def between(bundle_a, bundle_b)
+          a = units_by_anchor(bundle_a)
+          b = units_by_anchor(bundle_b)
+          {
+            "from" => document_id(bundle_a),
+            "to" => document_id(bundle_b),
+            "added" => (b.keys - a.keys).map { |k| summary(b[k]) },
+            "removed" => (a.keys - b.keys).map { |k| summary(a[k]) },
+            "changed" => (a.keys & b.keys).filter_map do |k|
+              next if a[k]["hash"] == b[k]["hash"]
+
+              changed_unit(a[k], b[k])
+            end,
+          }
+        end
+
+        # Write <dir>/<from>-to-<to>.diff.json; returns the path.
+        def export(bundle_a, bundle_b, to:)
+          diff = between(bundle_a, bundle_b)
+          name = "#{Mko.slug(diff["from"])}-to-#{Mko.slug(diff["to"])}.diff.json"
+          path = File.join(to, name)
+          File.write(path, JSON.pretty_generate(diff) + "\n")
+          path
+        end
+
+        private
+
+        def units_by_anchor(bundle)
+          File.readlines(File.join(bundle, "units.jsonl"))
+              .each_with_object({}) do |line, h|
+            unit = JSON.parse(line)
+            h[unit["anchor"]] = unit
+          end
+        end
+
+        def document_id(bundle)
+          JSON.parse(File.read(File.join(bundle, "document.json")))
+              .dig("ids", "canonical")
+        end
+
+        def summary(unit)
+          { "anchor" => unit["anchor"], "type" => unit["type"],
+            "number" => unit["number"], "title" => unit["title"] }
+        end
+
+        # Field-level detail: top-level fields first, then the payload
+        # sub-fields consumers act on (terminology changes, table row
+        # deltas, requirement restatements).
+        def changed_unit(old, new)
+          fields = %w[text title number obligation].select do |f|
+            old[f] != new[f]
+          end
+          fields.concat(payload_changes(old, new))
+          summary(new).merge("fields" => fields.uniq)
+        end
+
+        def payload_changes(old, new)
+          op = old["payload"] || {}
+          np = new["payload"] || {}
+          return [] if op == np
+
+          changed = []
+          %w[designations admitted deprecated definition statement
+             subject identifier klass caption columns].each do |f|
+            changed << f if op[f] != np[f]
+          end
+          if op["rows"] != np["rows"]
+            changed << "rows" \
+              "(+#{(np["rows"] || []).size - (op["rows"] || []).size})"
+          end
+          changed << "payload" if changed.empty? && op != np
+          changed
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/export.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    # The value an export returns: the bundle path (String-ducktyped,
+        # so existing callers keep working) plus the projection Result,
+        # so composite exporters (collections, alignments) derive from
+    # the same truth the bundle was written from — never by reading
+    # their own output back.
+    class Export
+      attr_reader :path, :result
+
+      def initialize(path, result)
+        @path = path
+        @result = result
+      end
+
+      def to_s
+        @path.to_s
+      end
+
+      def to_str
+        @path.to_s
+      end
+    end
+  end
+end

data/lib/metanorma/mko/mcp.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Metanorma
+  module Mko
+    # Reference MCP server over an MKO bundle (issue #53 item 9; the
+    # MN 116 contract: search_units / get_unit / walk_edges /
+    # edition_diff). Every tool is a read over bundle files — an agent
+    # consumes a Metanorma corpus without anyone building a RAG first.
+    # JSON-RPC 2.0 over stdio; drive via #handle lines or #run(io).
+    module Mcp
+      class Server
+        PROTOCOL = "2025-06-18"
+        TOOLS = [
+          { "name" => "search_units",
+            "description" => "Search the document's units by term " \
+                             "overlap over title and text; optional type filter",
+            "inputSchema" => {
+              "type" => "object",
+              "properties" => {
+                "query" => { "type" => "string" },
+                "type" => { "type" => "string",
+                            "enum" => %w[clause annex term table figure formula
+                                        note example sourcecode requirement
+                                        reference] },
+              },
+              "required" => %w[query],
+            } },
+          { "name" => "get_unit",
+            "description" => "Full unit by stable id (text + typed payload)",
+            "inputSchema" => {
+              "type" => "object",
+              "properties" => { "id" => { "type" => "string" } },
+              "required" => %w[id],
+            } },
+          { "name" => "walk_edges",
+            "description" => "Edges touching a unit (any kind, or one kind)",
+            "inputSchema" => {
+              "type" => "object",
+              "properties" => {
+                "unit_id" => { "type" => "string" },
+                "kind" => { "type" => "string" },
+              },
+            } },
+          { "name" => "edition_diff",
+            "description" => "Structured change set between two bundles of " \
+                             "the same document (anchors pair; hashes decide)",
+            "inputSchema" => {
+              "type" => "object",
+              "properties" => {
+                "bundle_a" => { "type" => "string" },
+                "bundle_b" => { "type" => "string" },
+              },
+              "required" => %w[bundle_a bundle_b],
+            } },
+        ].freeze
+
+        def initialize(bundle)
+          @bundle = bundle
+        end
+
+        # One JSON-RPC request line -> response line (or nil for
+        # notifications). The test surface: drive the protocol without
+        # spawning a process.
+        def handle(line)
+          req = JSON.parse(line)
+          return nil if req["id"].nil?
+
+          result =
+            case req["method"]
+            when "initialize"
+              { "protocolVersion" => PROTOCOL,
+                "capabilities" => { "tools" => {} },
+                "serverInfo" => { "name" => "metanorma-mko",
+                                  "version" => SCHEMA_VERSION } }
+            when "tools/list" then { "tools" => TOOLS }
+            when "tools/call" then call_tool(req["params"] || {})
+            end
+          return JSON.generate(
+            { "jsonrpc" => "2.0", "id" => req["id"],
+              "error" => { "code" => -32_601,
+                           "message" => "method not found: #{req['method']}" } }
+          ) if result.nil?
+
+          JSON.generate({ "jsonrpc" => "2.0", "id" => req["id"],
+                          "result" => result })
+        rescue StandardError => e
+          JSON.generate({ "jsonrpc" => "2.0", "id" => (req && req["id"]),
+                          "error" => { "code" => -32_603,
+                                       "message" => "#{e.class}: #{e.message}" } })
+        end
+
+        def run(io = $stdin)
+          io.each_line { |line| (out = handle(line)) && puts(out) }
+        end
+
+        private
+
+        def units
+          @units ||= File.readlines(File.join(@bundle, "units.jsonl"))
+                         .map { |l| JSON.parse(l) }
+        end
+
+        def edges
+          @edges ||= File.readlines(File.join(@bundle, "edges.jsonl"))
+                         .map { |l| JSON.parse(l) }
+        end
+
+        def call_tool(params)
+          name = params["name"]
+          args = params["arguments"] || {}
+          case name
+          when "search_units" then search_units(args)
+          when "get_unit" then get_unit(args)
+          when "walk_edges" then walk_edges(args)
+          when "edition_diff" then edition_diff(args)
+          else raise ArgumentError, "unknown tool: #{name}"
+          end
+        end
+
+        def search_units(args)
+          terms = args["query"].to_s.downcase.split(/[^\p{L}\p{N}]+/)
+                              .reject { |t| t.length < 2 }
+          pool = args["type"] ? units.select { |u| u["type"] == args["type"] } : units
+          scored = pool.filter_map do |u|
+            hay = "#{u['title']} #{u['text']}".downcase
+            score = terms.count { |t| hay.include?(t) }
+            { "id" => u["id"], "type" => u["type"], "anchor" => u["anchor"],
+              "number" => u["number"], "title" => u["title"],
+              "score" => score } if score.positive?
+          end
+          text(JSON.generate(scored.sort_by { |s| -s["score"] }.first(10)))
+        end
+
+        def get_unit(args)
+          unit = units.find { |u| u["id"] == args["id"] }
+          raise ArgumentError, "no unit #{args['id']}" unless unit
+
+          text(JSON.generate(unit))
+        end
+
+        def walk_edges(args)
+          picked = edges.select do |e|
+            (args["unit_id"].nil? || e["from"] == args["unit_id"] ||
+             e["to"] == args["unit_id"]) &&
+              (args["kind"].nil? || e["kind"] == args["kind"])
+          end
+          text(JSON.generate(picked.first(50)))
+        end
+
+        def edition_diff(args)
+          text(JSON.generate(Diff.between(args["bundle_a"], args["bundle_b"])))
+        end
+
+        def text(body)
+          { "content" => [{ "type" => "text", "text" => body }] }
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    # The in-memory bundle: what a projection produces and the Writer
+    # serializes. Format-shaped — the component set of MN 116 — so it
+    # lives with the format, constructed by the model-side walk in
+    # metanorma-document.
+    class Result
+      attr_reader :document, :units, :edges, :glossary, :bibdata,
+                  :bibliography, :identifiers, :assets, :unitsml, :flavor
+
+      def initialize(document:, units:, edges:, glossary:, bibdata:,
+                     bibliography:, identifiers:, assets: [], unitsml: [],
+                     flavor:)
+        @document = document
+        @units = units
+        @edges = edges
+        @glossary = glossary
+        @bibdata = bibdata
+        @bibliography = bibliography
+        @identifiers = identifiers
+        @assets = assets
+        @unitsml = unitsml
+        @flavor = flavor
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/collection.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      # collection.json — the family contract for collection bundles:
+      # membership and cross-document edges between documents that a
+      # metanorma collection.yml declares together (OIML R 60 parts,
+      # R 129/138/144 families).
+      class CollectionMember < Lutaml::Model::Serializable
+        attribute :bundle, :string
+        attribute :docidentifier, :string
+        attribute :identifier, :string
+        attribute :title, :string
+        attribute :edition, :string
+
+        json do
+          map "bundle", to: :bundle
+          map "docidentifier", to: :docidentifier
+          map "identifier", to: :identifier
+          map "title", to: :title
+          map "edition", to: :edition
+        end
+      end
+
+      class Collection < Lutaml::Model::Serializable
+        attribute :canonical, :string
+        attribute :short, :string
+        attribute :title, :string
+        attribute :edition, :string
+        attribute :members, CollectionMember, collection: true,
+                                              default: -> { [] }
+
+        json do
+          map "canonical", to: :canonical
+          map "short", to: :short
+          map "title", to: :title
+          map "edition", to: :edition
+          map "members", to: :members
+        end
+      end
+    end
+  end
+end